跨平台人脸识别 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 版本
# 最低支持2.17
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBC_
输出结果示例：
2.2 查看 GLIBCXX 版本
# 最低支持3.4.21版本
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.* | grep GLIBCXX
输出结果示例：
2.3 查看编译器 GCC 版本
# 最低支持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，执行以下命令:
sudo apt-get update
sudo apt-get installapt-transport-httpsca-certificates
curl \
software-properties-commonlsb-release
gnupg2
- 卸载旧版本（如果有）
sudo apt-get remove docker docker-engine docker.io containerd runc
- 更新 apt
sudo apt update
- 安装依赖
sudo apt install ca-certificates curl gnupg lsb-release -y
- 添加 Docker 官方 GPG Key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
- 添加 Docker 官方仓库
sudo add-apt-repository \"deb [arch=amd64] https://download.docker.com/linux/ubuntu \$(lsb_release -cs) \stable"
- 安装 Docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y
- 验证
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：
# 基于 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 构建镜像
构建镜像：
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 运行容器
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，说明服务启动成功。
此时可以访问：
http://<你的服务器IP>:<你的端口号>
注意事项：
- 容器名不能重复
- 一个激活码只能用一个容器，容器重启后会导致原激活码失效
4. 常见问题（FAQ）
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
| 访问不到服务 | 防火墙或端口未开放 | sudo ufw allow <你的端口> 开放端口 |
| Docker 构建慢 | 网络镜像源未替换 | 可换为阿里云或中科大镜像源 |
| Jar 启动失败 | JDK 版本不匹配 | 使用 java -version 确认 JDK 与项目一致 |
| 项目路径权限问题 | 未赋执行权限 | 使用 chmod +x face-demo.jar |
5. 总结
本文围绕虹软[人脸识别 SDK] (https://ai.arcsoft.com.cn/?utm_source=bokeyuan&&utm_medium=chenying)的跨平台部署，从 Windows 本地环境、Ubuntu 虚拟机到 Docker 容器化运行，完整梳理了实际项目在不同环境下的落地流程。通过逐步验证系统依赖、检查 glibc 与 libstdc++版本、配置 Java 运行环境、构建 Spring Boot Jar 包，再到最后使用 Docker 打包镜像并运行服务，整个过程展示了一个跨平台项目从开发环境过渡到生产环境的完整路径。希望能够帮助你在后续的工程中更加顺利地进行部署与上线。