本文面向在受限网络（企业防火墙 / 代理服务器环境）中部署虹软人脸识别 Linux Pro SDK 的开发与运维人员，解决在线激活连不上授权服务器的问题。全文基于虹软 SDK 在线授权机制与通用代理配置实践编写。
一、背景与适用场景
虹软 Linux Pro（ArcFace Linux Pro）人脸识别 SDK 采用「激活授权」机制：首次使用时需要通过在线激活接口与虹软授权服务器通信，激活成功后在本地生成激活文件；此后 SDK 启动时校验激活文件即可使用。本文以 Spring Boot（Java） 集成场景为例，说明在代理/受限网络环境下完成在线激活的配置方法。
典型受限网络场景：
- 服务器部署在企业内网，仅能通过 HTTP/HTTPS 代理访问外网。
- 出口防火墙只放行 80/443 端口，且需要域名白名单。
- 容器 / 虚拟机环境无直接外网出口，需经宿主机或专用代理转发。
二、在线激活原理
在线激活本质是 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 无法授权初始化。
- 正式码永久有效，激活一次即可；试用码仅在有效期内有效。
六、常见问题排查
七、备选方案：离线激活
若代理环境始终无法打通在线链路，可改用离线激活：
- 在可联网的机器上，从虹软官网/后台获取对应设备信息的离线授权文件。
- 将离线授权文件拷贝到目标服务器，调用离线授权接口activeOffline完成授权。
- 离线授权不依赖设备外网，适合完全隔离的内网环境。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
This paper is intended for the development and transport of Linux Pro SDK in restricted networks (enterprise firewall / proxy server environment) to address the failure of online activation to access authorized servers. The full text is based on the Rainbow SDK online authorization mechanism and the generic proxy configuration practice.
Background and applicable scenarios
Rainbow Linux Pro (ArcFace Linux Pro) human face recognition SDK uses the "activation authorization" mechanism: when first used, you need to communicate with the Rainbow power server via online activation interface and locally generate active files after activation; thereafter, the active file can be verified for active use when SDK is launched. This paper uses the Spring Boot (Java) integration scenario as an example of how to configure online activation in a proxy/limited network environment.
A typical restricted web scene:
- Servers are deployed on enterprise intranets and can only be accessed via HTTP/HTTPS agents.
- The exit firewall will only be available at the 80/443 port and will require a white list of domain names.
- The container/virtual machine environment is not directly exported from the offline and requires transmission through the host or a dedicated agent.
II. Principles for online activation
The essence of online activation is that SDK initiates HTTP requests from authorized servers. Therefore, the central issue of the proxy network environment is to enable SDK HTTP requests to reach through proxy charge.vd.arcsoftai.com.
2.1 Access AppID and SDKKkey
ActivatedOnline Online requires input of appId, sdkKey, and activeKey parameters, all of which are available through the Rainbow Soft Visual Open Platform:
- Register and log on to the Rainbow Soft Visual Open Platform (ai.arcsoft.com.cn) and complete the certification of business names as required by the Platform.
- Create applications in the console "My Applications ", fill in application names and types, and get appId after creation.
- Apply for a target SDK authorization (e.g. face recognition Linux Pro SDK) to get the Sdkkey, activeKey corresponding to the SDK. The formal authorization code is to be acquired through the purchase process and activated once permanently.
Note: appId, sdkKey and activeKey are tied to the application and SDK type, do not mix the parameters of other applications or SDK, otherwise the activation will not match the parameter error or device information.
III. Environmental preparedness and inspection
3.1 Confirmation of network connectivity
Check the connectivity of the authorized server first on the target server (expected failure when the agent is not configured, only baseline):
curl -v http://charge.vd.arcsoftai.com --connect-timeout 10
# Expected output: condition timed out / could not resolve host etc.
3.2 Application for release from network administrators
- Destination domain name: charge.vd.arcsoftai.com (80/HTTP)
- If the agent has a white list mechanism, add the above-mentioned domain names to the white list.
IV. ADMINISTICS
4.1 Configure system proxy environment variables
Key principles: ArcFace Java SDK calls the bottom C++ dynamic library through JNI, and online activation requests are actually initiated by the C++ network layer (instead of HtpurlConnect / OkHttp of Java), so JVM's -D proxy parameter is invalid for activation requests. The agent needs to be configured at the process environment variable level to give effect to the C++ web stack (following http proxy/https proxy). Spring Boot applies to configure in startup shell or systemmd:
# Temporary effective (current shell, start Spring Boot pre-configuration)
Export http proxy= "http:// ProxyIP:port"
Export https proxy=http:// proxy server IP:port
Export no proxy= "localhost, 127.0.0.1 Intranet segment"
# If the agent needs authentication
Export https proxy= "http://username:***@ proxy server IP:port"
# Start Spring Boot application (environmental variables passed to C++ network layer)
java -jar your-app.jar
Example of systemmd service permanence configuration:
# examples of service permanence configuration (injecting proxy environment variables through Envirronment)
# /etc/system/system/your-app.service [Service]
[Service]
Environment = "http proxy=http://agentIP:port"
Environment = "https proxy =http://agentIP:port"
Environment="no_proxy=localhost,127.0.0.1"
ExecStart=/usr/bin/java -jar /opt/your-app/your-app.jar
4.2 Validation of the validity of agents
# Configure agents, curl authentication (curl also follows environment variables)
curl -v http://charge.vd.arcsoftai.com --connect-timeout 15
# Expected: returns with proxy HTTP response (possibly 200/301/403, etc.) indicating that the link is open
As long as the authorized server HTTP response (regardless of status code) is available through the proxy, the network link is open and can continue to be activated.
V. Activation of call and validation
5.1 Call activated interface
Following the network link, the Spring Boot application start-up phase (e.g. @PostConstract or ApplicationRunner) calls the SDK online activation interface example:
// Code Display
int ret = faceEngine.activeOnline(appId, sdkKey,activeKey);
if (ret == 0) {
/ / Activate successfully, Activate file generated to specified path
Log.info (“Online activation success”);
} else {
/ / Searching for error code document for failure to locate
Log.error ("Online activation failed, error code: }," ret);
}
5.2 Activate successful inspections
- Confirms that the activation of ArcFacePro64.dat has been generated in the directory in which command line is located (must read and write permission).
- Active files cannot be modified, moved or deleted at will, otherwise SDK cannot authorize initialization.
- The official code is permanent and activated once; the trial code is valid only for the duration of its validity.
VI. Questionnaires on frequently asked questions
Options: offline activation
If the proxy environment remains unable to access the online link, it can be activated using offline instead:
- offline authorization documents for obtaining information on the corresponding equipment from the Rainbow Soft Network/backstage on connected machines.
- Copy offline authorized documents to the target server and call offline authorized interface active Offline to complete the authorization.
- offline is authorized not to rely on the equipment's offline and to be suitable for a fully segregated intranet environment.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.