代理网络环境下虹软 ArcFace Linux Pro SDK 在线激活实操指南

本文面向在受限网络（企业防火墙 / 代理服务器环境）中部署虹软人脸识别 Linux Pro SDK 的开发与运维人员，解决在线激活连不上授权服务器的问题。全文基于虹软 SDK 在线授权机制与通用代理配置实践编写。

一、背景与适用场景

虹软 Linux Pro（ArcFace Linux Pro）人脸识别 SDK 采用「激活授权」机制：首次使用时需要通过在线激活接口与虹软授权服务器通信，激活成功后在本地生成激活文件；此后 SDK 启动时校验激活文件即可使用。本文以 Spring Boot（Java） 集成场景为例，说明在代理/受限网络环境下完成在线激活的配置方法。

典型受限网络场景：

服务器部署在企业内网，仅能通过 HTTP/HTTPS 代理访问外网。
出口防火墙只放行 80/443 端口，且需要域名白名单。
容器 / 虚拟机环境无直接外网出口，需经宿主机或专用代理转发。

二、在线激活原理

项目	说明
授权服务器域名	charge.vd.arcsoftai.com（HTTP，80 端口）
激活接口	SDK 提供在线激活接口（Java SDK 中对应 `activeOnline`方法，位于 SDK 提供的 Jar 包中；底层通过 JNI 调用 C++ 动态库发起激活请求），传入 `appId`、`sdkKey`、`activeKey`
激活产物	激活成功后在指定路径生成激活文件，SDK 初始化前必须调用成功
激活结果	返回 0 表示成功，非 0 为失败（查错误码说明文档）

在线激活本质是 SDK 向授权服务器发起 HTTP 请求。因此代理网络环境的核心问题就是：让 SDK 的 HTTP 请求能够经由代理到达 charge.vd.arcsoftai.com。

2.1 获取 AppID 与 SDKKey

在线激活接口 activeOnline 需要传入 appId、sdkKey、activeKey三个参数，均通过虹软视觉开放平台获取：

注册并登录虹软视觉开放平台（ai.arcsoft.com.cn），按平台要求完成企业实名认证。
在控制台「我的应用」中创建应用，填写应用名称与类型，创建完成后获得 appId（对应激活接口的 appId）。
在应用中申请目标 SDK 授权（如人脸识别 Linux Pro SDK），获得该 SDK 对应的 sdkKey、activeKey。正式授权码需通过购买流程获取，激活一次永久有效。

注意：appId、sdkKey与 activeKey 与应用及 SDK 类型一一绑定，请勿混用其他应用或 SDK 的参数，否则激活会报参数错误或设备信息不匹配。

三、环境准备与检查

3.1 确认网络连通性

在目标服务器上先用 curl 验证到授权服务器的连通性（代理未配置时预期失败，仅作基线）：

curl -v http://charge.vd.arcsoftai.com --connect-timeout 10
# 预期输出：connection timed out / could not resolve host 等，说明直连不可达

3.2 向网络管理员申请放行

目的域名：charge.vd.arcsoftai.com（80/HTTP）
如代理有域名白名单机制，将上述域名加入白名单。

四、代理配置实操

4.1 配置系统代理环境变量

关键原理：ArcFace Java SDK 通过 JNI 调用底层 C++ 动态库，在线激活请求实际由 C++ 网络层发起（而非 Java 的 HttpURLConnection / OkHttp），因此 JVM 的 -D 代理参数对激活请求无效。代理需要配置在 进程环境变量 层，让 C++ 网络栈（遵循 http_proxy / https_proxy）生效。Spring Boot 应用在启动 shell 或 systemd 中配置：

# 临时生效（当前 shell，启动 Spring Boot 前配置）
export http_proxy="http://代理服务器IP:端口"
export https_proxy="http://代理服务器IP:端口"
export no_proxy="localhost,127.0.0.1,内网网段"

# 若代理需要认证
export https_proxy="http://用户名:***@代理服务器IP:端口"

# 启动 Spring Boot 应用（环境变量随进程传递给 C++ 网络层）
java -jar your-app.jar

systemd 服务持久化配置示例：

# systemd 服务持久化配置示例（通过 Environment 注入代理环境变量）
# /etc/systemd/system/your-app.service 的 [Service] 段
[Service]
Environment="http_proxy=http://代理IP:端口"
Environment="https_proxy=http://代理IP:端口"
Environment="no_proxy=localhost,127.0.0.1"
ExecStart=/usr/bin/java -jar /opt/your-app/your-app.jar

4.2 验证代理是否生效

# 配置代理后，curl 验证（curl 同样遵循环境变量）
curl -v http://charge.vd.arcsoftai.com --connect-timeout 15
# 预期：经代理返回 HTTP 响应（可能是 200/301/403 等），说明链路已通

只要能通过代理拿到授权服务器的 HTTP 响应（无论状态码），说明网络链路已打通，可继续尝试激活。

五、激活调用与验证

5.1 调用激活接口

网络链路打通后，在 Spring Boot 应用启动阶段（如 @PostConstruct 或 ApplicationRunner）调用 SDK 在线激活接口示例：

// 代码示意
int ret = faceEngine.activeOnline(appId, sdkKey,activeKey);
if (ret == 0) {
    // 激活成功，激活文件已生成到指定路径
    log.info("在线激活成功");
} else {
    // 查错误码文档定位失败原因
    log.error("在线激活失败，错误码：{}", ret);
}

5.2 激活成功后的检查

确认激活文件ArcFacePro64.dat已生成在命令行所在目录（务必有读写权限）。
激活文件不可随意修改、移动或删除，否则 SDK 无法授权初始化。
正式码永久有效，激活一次即可；试用码仅在有效期内有效。

六、常见问题排查

现象	可能原因	处理建议
激活返回网络类错误码	代理未生效 / 域名未放行	用 curl 验证链路；检查 http_proxy / https_proxy 环境变量是否随 Java 进程传递（C++ 层发起激活）；确认代理白名单含 charge.vd.arcsoftai.com
代理认证失败	代理需要账号密码	在 http_proxy / https_proxy 环境变量中携带用户名密码（如 http://用户名:密码@代理IP:端口），密码含特殊字符时需 URL 编码

七、备选方案：离线激活

若代理环境始终无法打通在线链路，可改用离线激活：

在可联网的机器上，从虹软官网/后台获取对应设备信息的离线授权文件。
将离线授权文件拷贝到目标服务器，调用离线授权接口activeOffline完成授权。
离线授权不依赖设备外网，适合完全隔离的内网环境。