设备证书（mTLS）导入手册

本手册用于把服务域名从「谁都能连」改为「只有安装设备证书的 App/EXE 能连」。方案基于 mTLS：内部 CA 签发设备证书，客户端在 TLS 握手中出示证书，服务端校验通过后才允许访问。

资料显示，CA 与三张设备证书已签发，服务端校验能力已实测通过；App/EXE 的证书支持仍在 task-14 / task-15 推进中。因此当前手册先覆盖证书获取、设备导入与验证，后续再逐个切换 vhost 强制校验。

证书位于 .164（xiejun-web）的 /opt/mtls：ca.crt 为内部 CA 根证书；clients/<CN>.crt / .key 为设备证书与私钥；export/<CN>.p12 为导入用打包文件，口令在 export/passphrase.txt。已签发 CN 包括 find5-xiejun、k50-xiejun、win-xiejun，另有测试用 test-device。

使用时需将 p12 拷到设备并导入系统证书库，再用带证书与不带证书的请求验证服务端行为。注意不要把口令、私钥、p12 贴进聊天、文档或仓库。

功能

• 提供内部 CA 根证书与设备证书的存放位置说明
• 覆盖 Android 7/12 与 Windows 11 的 p12 导入步骤
• 给出带证书/不带证书的服务端校验命令与预期结果
• 说明 vhost 从 optional 切到 on 的后续流程与回滚方式
• 提供撤销设备权限的参考做法

技术栈

使用 / 部署教程

1. 获取证书包与口令

在 .164（xiejun-web）上，证书位于 /opt/mtls。导入用文件为 /opt/mtls/export/<CN>.p12，口令在 /opt/mtls/export/passphrase.txt。在能登录 .164 的机器上取口令：

ssh nas 'sudo cat /opt/mtls/export/passphrase.txt'

不要把口令、私钥、p12 贴进聊天/文档/仓库。

2. 拷贝到设备

手机示例（K50）：先拷到下载目录，再通过 adb 推送到设备。

ssh nas 'sudo base64 -w0 /opt/mtls/export/k50-xiejun.p12' | base64 -d > /tmp/k50-xiejun.p12
adb -s 192.168.50.112:5555 push /tmp/k50-xiejun.p12 /sdcard/Download/k50-xiejun.p12

Windows 可用 scp 将 p12 放到 C:/Users/Administrator/Downloads/。

3. 导入证书

Android 7/12：设置 → 安全（或「密码与安全」）→ 加密与凭据 → 安装证书 → VPN 和应用 → 选 *.p12 → 输入口令 → 起名字。MIUI 路径为：设置 → 密码与安全 → 系统安全 → 加密与凭据 → 安装证书 → 凭据用途选「VPN 和应用」。

Windows 11：

$pw = Read-Host -AsSecureString "p12 口令"
Import-PfxCertificate -FilePath "$env:USERPROFILE\Downloads\win-xiejun.p12" -CertStoreLocation Cert:\CurrentUser\My -Password $pw
Get-ChildItem Cert:\CurrentUser\My | Where-Object { $_.Subject -like "*win-xiejun*" }

4. 验证服务端校验

带证书访问测试域，应返回 verify: SUCCESS 与 CN=；不带证书应返回 400 No required SSL certificate was sent。

5. 后续切换与回滚

等 App v1.6.0 / EXE v0.9.0 支持后，确认两端都能拿到 SUCCESS，再把要隐藏的 vhost 从 ssl_verify_client optional 改成 on，逐个切、切一个验一个。回滚时改回 off（或删掉两行）并执行 docker exec npm nginx -s reload。

6. 撤销设备权限

若使用 CA 数据库，可执行 openssl ca -config /opt/mtls/openssl.cnf -revoke /opt/mtls/clients/<CN>.crt；当前 CA 未建索引数据库，最稳方式是重新生成 CA 并重签全部设备证书。

常见问题