跨平台人脸识别 SDK 部署指南

（Linux 本地环境 → 虚拟机 → Docker全流程清晰讲解）

1. 部署背景与环境架构概述

1.1 部署背景

在开发跨平台人脸识别系统的过程中，一个常见的痛点是：

SDK 本地能跑，但移植到 Linux、Docker等环境就各种依赖缺失、GLIBC 不兼容。

笔者最近完成了虹软人脸识别 SDK 的 Spring Boot + Vue3 项目在 Linux 环境的部署。本文将带你从零开始梳理工程落地流程，帮助你在 Linux 实机/虚拟机 + Docker 容器 中顺利运行 Linux Pro SDK。

1.2 本地 / 虚拟机 / Docker 架构说明

为了顺利部署项目，我们先明确几个关键概念：物理机、虚拟机、容器（Docker）分别是什么，其区别是什么。

1.2.1 本地物理机

直接运行在计算机硬件上的系统，例如你的 Windows 或 Linux 主机。

特点：

优点	缺点
性能好、简单易用	环境不可复制、迁移困难
无虚拟层，速度最快	配置易污染、维护困难

适合场景：

本地开发
小规模测试

1.2.2 虚拟机（VM）

在 Windows 中通过 Hyper-V、VirtualBox、VMware 启动一个 完整的 Ubuntu 系统。

特点：

优点	缺点
隔离性完美	内存占用大、启动慢
能模拟真实生产环境	镜像大，不宜扩展

适合：

开发环境模拟生产环境
多系统测试（Windows 上跑 Linux）

1.2.3 Docker 容器

共享宿主机内核，无需每个实例都安装完整系统。

容器 vs 虚拟机对比：

对比项	虚拟机	Docker
启动速度	分钟级	秒级
占用资源	多（独立系统）	少（共享内核）
部署环境	难以复制	一致可复现

适合：

生产环境
微服务架构
DevOps、CI/CD 自动化

举例： 你可以把一个 Java Spring Boot 应用打包成一个 Docker 镜像，交给任何机器运行，不需要安装 JDK 或配置环境变量。

2. 环境依赖与版本检查

本文涉及的三层环境（Host → VM → Docker）：

复制代码

Windows 主机
 └── Ubuntu 虚拟机（VirtualBox）
      └── Docker 容器（运行 SDK Demo）

具体版本如下：

环境	推荐版本
Host OS	Windows 11
VM OS	Ubuntu 18.04
Docker Base	Ubuntu:18.04
SDK	ArcSoft_ArcFacePro_linuxPro

Linux 环境必要依赖检查

SDK 大多依赖特定版本的：

GLIBC
GLIBCXX（libstdc++）
GCC

推荐优先检查：

2.1 查看 GLIBC 版本

bash 复制代码

#  最低支持2.17
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBC_

输出结果示例：

2.2 查看 GLIBCXX 版本

bash 复制代码

# 最低支持3.4.21版本
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBCXX

输出结果示例：

2.3 查看编译器 GCC 版本

bash 复制代码

# 最低支持4.8.2
gcc --version

输出结果示例：

3. SDK 部署流程

在日常开发中，我们通常在 Windows 环境中进行项目调试与测试，而最终的生产部署多运行在 Linux 服务器上。以虹软人脸识别 SDK 为例，其官方 Demo 是基于 Spring Boot + Vue3 实现的完整后端与前端系统。为了将该系统迁移至 Linux 服务器运行，我们需要完成以下任务：

在 Linux 系统（或 WSL Ubuntu 子系统）中搭建运行环境。
将项目打包成可执行 JAR 文件。
在服务器上运行并验证。
使用 Docker 容器化运行，方便部署与迁移。

3.1 在 Linux 部署 JAR 服务（本地物理机部署 jar 包）

由于虹软官方源码是java环境，所以我们运行该demo需要先配置java环境，可以先检查一下自己的系统里是否有安装（jdk推荐安装1.8版本）：

java -version

输出示例：

可以看到linux环境（Ubuntu 18）里是没有安装Java的，这里我们根据提示安装，default-jre在Ubuntu 18系统里默认是11版本：

sudo apt install openjdk-11-jre-headless

输出示例：

安装完成后可以再次查看java -version：

出现11.0.19的字样就说明安装成功了，接下来我们可以在本地跑一下虹软的demo了，首先从官网下载server源码demo：

下载后使用idea运行该项目，并修改appid 、sdk-key、 active-key ，用maven编译该demo的jar包：

为了方便运行，给这个jar包改名为face-demo.jar，并放到项目根目录下：

然后执行命令：

java -jar face-demo.jar

输出示例：

等待程序运行，运行成功会出现以下界面，点击访问默认访问地址则可以访问该网站：

log中没有出现错误则表示运行成功，访问则可以看到下面的网页：

注意事项：

如若访问失败，可以看下命令行log中有没有激活失败的问题，如果激活失败则更重复一下上述修改 appid 、sdk-key、

active-key 的步骤，下图 active-key 被使用后则激活失败：

3.2 使用 Docker 部署 SDK（使用 Docker 容器部署 jar 包）

3.2.1 准备 Docker 容器（安装 Docker）

安装Docker，执行以下命令:

sql 复制代码

sudo apt-get update
sudo apt-get installapt-transport-httpsca-certificates
curl \
software-properties-commonlsb-release
gnupg2

卸载旧版本（如果有）

arduino 复制代码

sudo apt-get remove docker docker-engine docker.io containerd runc

更新 apt

sql 复制代码

sudo apt update

安装依赖

arduino 复制代码

sudo apt install ca-certificates curl gnupg lsb-release -y

添加 Docker 官方 GPG Key

arduino 复制代码

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

添加 Docker 官方仓库

bash 复制代码

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

安装 Docker

lua 复制代码

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y

验证

arduino 复制代码

docker --version
sudo docker run hello-world

安装成功示例如下：

3.2.2 准备 JAR 包

使用虹软官方demo构建jar包（face-demo-docker.jar），可以参考3.1中下载步骤，这里不再赘述

3.2.3 准备一个基础 Dockerfile

我们需要了解一下什么是 Dockerfile，Dockerfile 就是一份 构建 Docker 镜像的"配方" 。只要写好 Dockerfile，执行 docker build，Docker 就能自动：

拉镜像
复制文件
安装依赖
启动你的 SpringBoot Jar
打包成一个可运行的镜像

接下来我们在项目根目录创建一个 Dockerfile：

bash 复制代码

# 基于 JDK 11 镜像
FROM eclipse-temurin:11-jdk-jammy

# 工作目录
WORKDIR /app

#复制jar文件
COPY face-demo-docker.jar /app/app.jar

# 声明容器在运行时会监听的端口号，这里的端口号只是一个声明，不会真正打开端口，也不会影响容器运行
# 真正决定外部访问端口的是：docker run -p 宿主机端口:容器端口
EXPOSE 8089

# 容器启动命令
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

3.2.4 构建镜像

构建镜像：

arduino 复制代码

docker build -t face-demo-image:v1 .

docker build：构建镜像的命令。

-t face-demo-image:latest：给生成的镜像打上一个标签（tag）。

face-demo-image 是镜像名称；
latest 是标签（一般表示最新版，可自定义，比如 v1）。

.：表示构建上下文（context）为当前目录，也就是说它会在当前目录查找 Dockerfile 文件并打包所有内容。

注意事项：

docker相同镜像名 + 相同 tag（完全重复）→ 会被覆盖，none就是被覆盖的那个，建议build镜像前先检查一下已有的镜像

相同镜像名+不同tag，则可以共存

删除相同镜像名+不同tag则要删除对应tag

3.2.5 运行容器

arduino 复制代码

docker run -it -p 9000:8089 --name arcface-container face-demo-image:v1

参数	作用
`docker run`	创建并运行一个新容器
`-it`	进入交互式终端（前台），后台运行使用-d
`-p 9000:8089`	端口映射：将宿主机的 `9000` 端口映射到容器的 `8089` 端口(8089是jar包里面定义的端口号）
`--name arcface-container`	给容器取名为 `arcface`，方便后续管理
`face-demo-image:v1`	指定要运行的镜像名称和版本标签（你之前 build 的镜像）

查看运行状态：

复制代码

docker ps

输出示例

若容器状态为 Up，说明服务启动成功。此时可以访问：

xml 复制代码

http://<你的服务器IP>:<你的端口号>

注意事项：

容器名不能重复

一个激活码只能用一个容器，容器重启后会导致原激活码失效

4. 常见问题（FAQ）

问题	可能原因	解决方法
访问不到服务	防火墙或端口未开放	`sudo ufw allow <你的端口>` 开放端口
Docker 构建慢	网络镜像源未替换	可换为阿里云或中科大镜像源
Jar 启动失败	JDK 版本不匹配	使用 `java -version` 确认 JDK 与项目一致
项目路径权限问题	未赋执行权限	使用 `chmod +x face-demo.jar`

5. 总结

本文围绕虹软人脸识别 SDK的跨平台部署，从 Windows 本地环境、Ubuntu 虚拟机到 Docker 容器化运行，完整梳理了实际项目在不同环境下的落地流程。通过逐步验证系统依赖、检查 glibc 与 libstdc++版本、配置 Java 运行环境、构建 Spring Boot Jar 包，再到最后使用 Docker 打包镜像并运行服务，整个过程展示了一个跨平台项目从开发环境过渡到生产环境的完整路径。希望能够帮助你在后续的工程中更加顺利地进行部署与上线。