【Ubuntu部署】人脸特征提取SDK完整部署教程（含Nginx代理+问题排查）

本文适配Ubuntu全系列（18.04/20.04/22.04）和CentOS 8系统，详细讲解人脸特征提取SDK的环境搭建、依赖安装、服务启动及Nginx代理配置，附带双系统常见报错解决方案，新手可直接跟着操作，避免踩坑！

一、文档说明

✅ 核心用途：指导Ubuntu、CentOS 8系统中完成人脸特征提取SDK部署，包括环境配置、依赖安装、Java服务启动及Nginx代理配置。

✅ 适用系统：Ubuntu 18.04/20.04/22.04（其他Ubuntu版本可参考）、CentOS 8

✅ 核心目标：搭建稳定运行环境，确保SDK正常调用，实现人脸特征提取功能。

⚠️ 说明：文档中所有步骤均区分「Ubuntu系统」和「CentOS 8系统」，请根据自身系统选择对应命令操作，避免混淆。

二、前置环境准备

2.1 系统更新（必做）

更新软件源，修复损坏依赖，避免后续安装报错（root权限，加sudo即可）：

bash 复制代码

# ------------------- Ubuntu系统 -------------------
# 更新apt软件源
sudo apt-get update
# 修复损坏依赖
sudo apt-get -f install
# 系统整体更新
sudo apt-get upgrade

# ------------------- CentOS 8系统 -------------------
# 清理缓存并更新yum源
sudo yum clean all
sudo yum makecache
# 系统整体更新
sudo yum update -y

2.2 创建部署目录（双系统通用）

统一管理软件和应用文件，执行命令创建目录：

bash 复制代码

# 软件主目录
sudo mkdir -p /usr/software
# 软件下载目录
sudo mkdir -p /usr/software/download
# SDK及Java服务部署目录
sudo mkdir -p /usr/web_application

三、核心依赖安装（依次执行，缺一不可）

区分双系统命令，适配各自系统包管理器（Ubuntu用apt，CentOS 8用yum），按顺序执行即可，无需额外配置。

3.1 网络相关工具（net-tools）

用于排查网络和端口问题，必备工具：

bash 复制代码

# ------------------- Ubuntu系统 -------------------
sudo apt-get install net-tools -y

# ------------------- CentOS 8系统 -------------------
# CentOS 8默认无net-tools，需手动安装
sudo yum install net-tools -y

✅ 验证：执行ifconfig或ip addr，能显示网卡信息即为安装成功。

3.2 网络工具（curl + wget）

用于下载文件、调试接口：

bash 复制代码

# ------------------- Ubuntu系统 -------------------
sudo apt-get install curl wget -y

# ------------------- CentOS 8系统 -------------------
sudo yum install curl wget -y

3.3 编译工具（gcc + g++ + make）

SDK底层依赖C/C++编译，必须安装：

bash 复制代码

# ------------------- Ubuntu系统 -------------------
sudo apt-get install gcc g++ make -y

# ------------------- CentOS 8系统 -------------------
sudo yum install gcc g++ make -y

3.4 核心运行库

SDK运行必需的基础库，双系统对应命令如下：

bash 复制代码

# ------------------- Ubuntu系统 -------------------
# C运行库（Ubuntu默认已装，更新至最新）
sudo apt-get install libc6 -y
# 正则表达式库（Nginx依赖）
sudo apt-get install libpcre3-dev -y
# 加密库（保障数据安全）
sudo apt-get install openssl libssl-dev -y
# 压缩库（解压安装包）
sudo apt-get install zlib1g zlib1g-dev -y

# ------------------- CentOS 8系统 -------------------
# C运行库（CentOS 8默认已装，更新至最新）
sudo yum install glibc -y
# 正则表达式库（Nginx依赖）
sudo yum install pcre-devel -y
# 加密库（保障数据安全）
sudo yum install openssl openssl-devel -y
# 压缩库（解压安装包）
sudo yum install zlib zlib-devel -y

3.5 其他依赖

bash 复制代码

# ------------------- Ubuntu系统 -------------------
# 脚本语言（TCL）
sudo apt-get install tcl -y
# MySQL依赖（SDK关联数据库时必装）
sudo apt install libaio-dev -y
# 版本控制工具（git）
sudo apt-get install git -y
# 解压工具（支持ZIP/7Z）
sudo apt-get install unzip p7zip-full -y
# Tomcat加速（关联Tomcat时必装）
sudo apt install rng-tools -y
# 时间同步（避免时间偏差导致接口报错）
sudo apt-get install chrony -y
# 启动chrony并设置开机自启
sudo systemctl start chronyd
sudo systemctl enable chronyd

# ------------------- CentOS 8系统 -------------------
# 脚本语言（TCL）
sudo yum install tcl -y
# MySQL依赖（SDK关联数据库时必装）
sudo yum install libaio-devel -y
# 版本控制工具（git）
sudo yum install git -y
# 解压工具（支持ZIP/7Z）
sudo yum install unzip p7zip -y
# Tomcat加速（关联Tomcat时必装）
sudo yum install rng-tools -y
# 时间同步（CentOS 8默认用chronyd，无需额外安装）
sudo systemctl start chronyd
sudo systemctl enable chronyd

✅ 时间同步验证：执行date，显示正确北京时间即可。

四、Go环境代理配置（SDK依赖，双系统通用）

若SDK依赖Go模块，需配置国内代理，避免下载失败（重点注意：多个代理地址存在网页解析失败，已更新可用方案）。

4.1 编辑环境变量配置文件

bash 复制代码

# ------------------- Ubuntu系统 -------------------
sudo vim /etc/profile

# ------------------- CentOS 8系统 -------------------
sudo vim /etc/profile

4.2 添加Go代理（复制粘贴即可，优先使用可用代理）

⚠️ 在文件末尾添加以下内容（优先使用goproxy.cn，备选阿里云代理）：

bash 复制代码

# 优先使用goproxy.cn官方标准配置（需确保Go 1.13及以上版本）
export GOPROXY=https://goproxy.cn/
export GOPROXY=https://mirrors.aliyun.com/goproxy/
# 说明：goproxy.cn为国内可信Go模块代理，支持无带宽、无速率限制，加速Go模块下载，适配所有Go 1.13及以上版本。

4.3 刷新配置，使其生效（双系统通用）

bash 复制代码

source /etc/profile

五、JDK17安装（Java服务必需，双系统通用）

人脸特征提取SDK关联的Java服务（BjxDmsWebSdk1.jar）需JDK17环境支撑，以下为JDK17安装步骤

5.1 下载JDK17

bash 复制代码

# 进入软件下载目录
cd /opt/
# 下载JDK17安装包
wget https://mirrors.tuna.tsinghua.edu.cn/Adoptium/17/jdk/x64/linux/OpenJDK17U-jdk_x64_linux_hotspot_17.0.18_8.tar.gz

5.2 解压JDK至指定目录（双系统通用）

bash 复制代码

# 解压到/opt目录（路径可自定义，后续同步修改即可）
sudo tar zxf OpenJDK17U-jdk_x64_linux_hotspot_17.0.18_8.tar.gz -C /opt/
sudo chmod 777 /usr/1ib/aiva_face_sdk/  # 必须执行
sudo mkdir /usr/lib/aiva_face_sdk/face_feature # 必须执行 否则提取人脸特征失败

✅ 解压后JDK目录：/opt/jdk\-17\.0\.18\+8

六、Java服务启动（SDK核心关联服务，双系统通用）

⚠️ 报错提示：直接访问 http://127\.0\.0\.1:6999/（含带后缀版本）会提示"URL拼写可能存在错误"，无需修改URL，重点验证服务和端口是否正常即可，该报错不影响SDK调用。

6.1 启动Java服务（后台运行，避免断开连接失效）

bash 复制代码

nohup /opt/jdk-17.0.18+8/bin/java -jar -Duser.timezone=Asia/Shanghai -Xmx2048M -Xms1024M /opt/BjxDmsWebSdk1.jar --server.port=6999 > bjxdms.log 2>&1

6.2 命令参数说明（新手可忽略，按需调整）
/opt/jdk\-17\.0\.18\+8/bin/java：JDK执行路径（按实际解压路径修改）
\-Duser\.timezone=Asia/Shanghai：设置北京时间，避免时间偏差
\-Xmx2048M：JVM最大堆内存（按需调整，如1024M、4096M）
\-Xms1024M：JVM初始堆内存
\-\-server\.port=6999：服务端口（可修改，避免冲突）
\> bjxdms\.log 2\>\&1 &：后台运行，日志输出至bjxdms.log

6.3 服务验证（关键步骤，必做）

bash 复制代码

# 查看服务进程（是否启动成功）
ps -ef | grep BjxDmsWebSdk1.jar
# 查看6999端口监听情况（排查URL报错问题）
netstat -tulnp | grep 6999
# 查看日志，确认无报错
tail -f bjxdms.log

✅ 验证成功标准：进程存在、6999端口监听、日志无报错，此时SDK可正常被调用。

6.4 关键步骤（必做！否则识别报错）

启动Java服务并验证成功后，需手动将SDK授权文件（如license.dat）复制至Java服务jar包同级目录（本文中为/opt目录），并赋予权限，否则会导致人脸特征提取识别报错，执行以下命令（双系统通用）：

bash 复制代码

# 重启Java服务，使授权文件生效
sudo pkill -f BjxDmsWebSdk1.jar
nohup /opt/jdk-17.0.18+8/bin/java -jar -Duser.timezone=Asia/Shanghai -Xmx2048M -Xms1024M /opt/BjxDmsWebSdk1.jar --server.port=6999 > bjxdms.log 2>&1

⚠️ 注意：授权文件名称和路径需按实际情况修改，若未配置授权文件或权限不足，会直接导致SDK识别功能报错，无法正常使用。

七、Nginx配置（接口访问代理，必做）

配置Nginx反向代理，通过http://服务器IP:10009/api/doc/swagger\-ui/index\.html访问SDK接口文档，便于调试，双系统配置步骤一致，仅安装命令不同。

7.1 安装Nginx（若未安装）

bash 复制代码

# ------------------- Ubuntu系统 -------------------
sudo apt-get install nginx -y
# 启动Nginx并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx

# ------------------- CentOS 8系统 -------------------
# CentOS 8默认yum源无Nginx，需先安装epel源
sudo yum install epel-release -y
# 安装Nginx
sudo yum install nginx -y
# 启动Nginx并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx

7.2 配置Nginx反向代理（双系统通用）

bash 复制代码

# 编辑Nginx配置文件
sudo vim /etc/nginx/nginx.conf

在http块内添加以下配置（复制粘贴，放在原有server配置后即可）：

nginx 复制代码

server {
	listen       10009;
	server_name  localhost;
	charset utf-8;
	client_max_body_size 1024m; # 支持大文件上传

	location /api/ {
		proxy_pass http://127.0.0.1:6999/;
		proxy_set_header Host $Host:$server_port;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header REMOTE-HOST $remote_addr;
		add_header X-Cache $upstream_cache_status;
		proxy_set_header X-Host $host:$server_port;
		proxy_set_header X-Scheme $scheme;
		proxy_connect_timeout 30s;
		proxy_read_timeout 86400s;
		proxy_send_timeout 30s;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
	}

	error_page   500 502 503 504  /50x.html;
	location = /50x.html {
		root   html;
	}
}

7.3 配置生效与验证（双系统通用）

bash 复制代码

# 检查配置语法（避免报错）
sudo nginx -t
# 重启Nginx，使配置生效
sudo systemctl restart nginx 或者 nginx -s reload

7.4 访问SDK接口文档（双系统通用）

配置生效后，浏览器访问以下地址，即可查看和调试SDK接口：

text 复制代码

http://服务器IP:10009/api/doc/swagger-ui/index.html

⚠️ 注意：将"服务器IP"替换为实际服务器的局域网/公网IP，确保10009端口已开放；CentOS 8需额外开放端口（执行命令：sudo firewall-cmd --add-port=10009/tcp --permanent && sudo firewall-cmd --reload）。

八、常见报错解决方案（重点！避免踩坑，双系统适配）

依赖安装失败：Ubuntu系统用apt/apt-get命令，CentOS 8用yum命令；提示软件包不存在，Ubuntu执行sudo apt\-get update，CentOS 8执行sudo yum makecache更新源。

Go代理无效：优先使用goproxy.cn官方标准配置（搭配GO111MODULE=on）；若仍解析失败，执行自建代理步骤，替换代理为http://localhost:8080（双系统通用）。

JDK下载失败：放弃所有镜像下载，通过本地下载OpenJDK17安装包，再用scp/ftp上传至服务器对应目录（双系统通用）。

Java服务启动失败：检查JDK路径、jar包路径是否正确；用netstat \-tulnp \| grep 6999排查端口占用（双系统通用）。

URL拼写错误提示：访问http://127\.0\.0\.1:6999/出现该提示属正常现象，无需修改URL，优先排查Java服务是否启动、6999端口是否监听（双系统通用）。

Nginx配置失效：用sudo nginx \-t检查语法；确认10009端口未占用，Nginx和Java服务均正常运行；CentOS 8需额外检查防火墙端口是否开放。

Swagger文档无法访问：确认Java服务启动、6999端口监听；检查Nginx代理路径配置；CentOS 8需开放10009端口，Ubuntu需确认端口未被防火墙拦截。

SDK识别报错：优先检查是否执行"6.4 关键步骤"，确认授权文件已复制至对应目录且权限正确，重启Java服务后重试（双系统通用）。

CentOS 8 Nginx安装失败：未安装epel源，先执行sudo yum install epel\-release \-y，再重新安装Nginx。

CentOS 8 端口无法访问：防火墙未开放对应端口，执行sudo firewall\-cmd \-\-add\-port=端口号/tcp \-\-permanent \&\& sudo firewall\-cmd \-\-reload（如10009、6999端口）。

九、注意事项（双系统适配）

所有命令需root权限，可在命令前加sudo，或直接切换至root用户（双系统通用）。

JDK、jar包、SDK的部署路径可自定义，修改后需同步更新启动命令和Nginx配置（双系统通用）。

SDK若需授权文件、模型文件，需放在指定目录，执行sudo chmod 777 文件名赋予权限（双系统通用）。

建议将Java服务设置为开机自启，避免服务器重启后服务失效（可通过编写systemd服务实现，双系统通用）。

网络相关报错（代理、下载失败），先检查服务器网络连接，优先使用本地上传、自建代理等替代方案（双系统通用）。

务必执行"6.4 关键步骤"，未配置授权文件或权限不足，会直接导致SDK识别报错，无法正常实现人脸特征提取功能（双系统通用）。

Go代理、JDK镜像多个地址均存在解析失败，严格按照本文补充的"本地上传""自建代理"步骤操作，避免无效尝试（双系统通用）。

CentOS 8需注意防火墙配置，部署过程中涉及的端口（6999、10009）需手动开放，否则会导致接口无法访问。

CentOS 8安装Nginx需先安装epel源，否则会提示"无可用软件包"，严格按照步骤执行。