这一篇开始实操。目标：让你把工程在本地或服务器上跑起来，访问 Web 联调页面，并确认默认配置已经加载。

---

1. 准备环境

需要：

工具	建议
JDK	Java 8 或兼容本工程的 JDK
Maven	能下载公网 Maven 依赖，或公司内网镜像已配置
网络	部署机能访问远端 your-ip:your-port
证书	至少有服务端 CA 根证书/中间 CA 证书
客户端证书	只有双向认证时需要

先检查：

java -version
mvn -version

---

2. 看清工程默认配置

打开：

src/main/resources/application.yml

关键配置：

server:
  port: 9876

gm:
  tlcp:
    scheme: https
    host: your-ip
    port: your-port
    upload-path: /context-path/v1/file/upload
    tls:
      protocol: TLCPv1.1
      enabled-protocols:
        - TLCPv1.1
      enabled-cipher-suites:
        - TLCP_ECC_SM4_GCM_SM3
        - TLCP_ECC_SM4_CBC_SM3
      client-signature-schemes:
        - sm2sig_sm3
      hostname-verification-enabled: false
      trust-certificates:
        - classpath:certs/ROOTCA.cer
        - classpath:certs/BeijingSM2CA.cer

解释：

• 本服务自己监听 9876，用于浏览器联调页面；
• 远端 TLCP 服务是 your-ip:your-port；
• 远端接口路径是 /context-path/v1/file/upload；
• TLCP 协议版本是 TLCPv1.1；
• 默认只启用两个 ECC 套件；
• 默认信任 classpath 里的两张 CA；
• 默认关闭 hostname verification，以兼容内网 IP 证书。

---

3. 放置 CA 证书

本工程已经把根目录的证书复制到：

src/main/resources/certs/ROOTCA.cer
src/main/resources/certs/BeijingSM2CA.cer

所以默认配置可以直接使用：

trust-certificates:
  - classpath:certs/ROOTCA.cer
  - classpath:certs/BeijingSM2CA.cer

3.1 什么时候用 classpath

适合：

• demo；
• 内部临时工具；
• 证书不敏感、更新频率低；
• 打包后希望开箱即用。

缺点：证书更新要重新打包。

3.2 什么时候用 file

生产更推荐：

trust-certificates:
  - file:/etc/gmssl/certs/ROOTCA.cer
  - file:/etc/gmssl/certs/BeijingSM2CA.cer

优点：

• 证书可以由运维独立更新；
• 不需要重新构建 jar；
• 权限可以由系统控制。

3.3 能不能写相对路径

可以。TlcpSslContextFactory.resolveResource() 找不到 Spring Resource 时，会当本地文件路径兜底。

示例：

trust-certificates:
  - ./certs/ROOTCA.cer

但生产建议用明确的 file:/absolute/path，减少工作目录变化导致的问题。

---

4. 如果需要客户端证书

如果服务端要求双向认证，你要把客户端证书和私钥做成 PKCS12 或 JKS。

本工程配置入口：

gm:
  tlcp:
    tls:
      client-key-store:
        path: file:/secure/client.p12
        type: PKCS12
        password: changeit
        key-password: changeit

含义：

字段	含义
path	KeyStore 文件位置
type	PKCS12 或 JKS
password	KeyStore 口令
key-password	私钥口令；为空时用 password

注意：

• 不要把真实生产密码提交进 Git；
• 不要把生产客户端私钥打进 jar；
• 如果你只有 .cer，那通常只是证书，没有私钥，不能当客户端 KeyStore 用。

---

5. 构建前先跑测试

执行：

mvn test

这个命令能验证：

• Maven 依赖是否可用；
• Kona Provider 是否能注册；
• 默认 classpath 证书是否能被读取；
• SSLContext("TLCPv1.1", "KonaSSL") 是否能创建；
• 请求 DTO 的默认值和列表解析是否正常；
• Content-Meta JSON 序列化是否符合预期。

如果这里失败，先别急着连远端。先把本地工程修好。

---

6. 打包

执行：

mvn package

成功后会生成：

target/gm-ssl-client-0.0.1-SNAPSHOT.jar

---

7. 启动联调服务

执行：

java -jar target/gm-ssl-client-0.0.1-SNAPSHOT.jar

默认不会马上请求远端，因为：

gm:
  upload:
    run-on-startup: false

启动日志里应该能看到类似：

Registered security provider: KonaCrypto
Registered security provider: KonaPKIX
Registered security provider: KonaSSL
Startup upload is disabled. Set gm.upload.run-on-startup=true to send the sample request.

如果没有 Provider 日志，也不一定失败，因为日志级别可能不同；但后续 /api/tlcp/upload 里会真正初始化。

---

8. 访问 Web 联调页面

浏览器打开：

http://127.0.0.1:9876/

如果部署在服务器：

http://<服务器IP>:9876/

页面会加载 /api/tlcp/defaults，把默认配置填进表单。

你应该看到这些默认值：

表单项	默认值
Scheme	https
Host	your-ip
Port	your-port
Upload Path	/context-path/v1/file/upload
SSLContext Protocol	TLCPv1.1
Enabled Protocols	TLCPv1.1
Cipher Suites	TLCP_ECC_SM4_GCM_SM3 / TLCP_ECC_SM4_CBC_SM3
Trust Certificates	两个 classpath 证书
Hostname Verification	未勾选
Content-Meta	默认 JSON

---

9. 如果页面打不开

9.1 本机打不开

检查进程是否启动、端口是否被占用：

lsof -i :9876

如果端口被占用，可以启动时改端口：

java -jar target/gm-ssl-client-0.0.1-SNAPSHOT.jar --server.port=9888

如果看TLCP的详细日志：

-Dcom.tencent.kona.ssl.debug=all  -Djavax.net.debug=ssl:handshake:verbose

9.2 远程打不开

检查：

• 服务器防火墙是否开放 9876；
• 安全组是否放行；
• 服务是否绑定在可访问地址；
• 浏览器访问的是 http://，不是 https://。

本工程的联调页面自己是普通 HTTP；它发出去的远端请求才是 TLCP/HTTPS。

---

10. 如果证书文件找不到

错误可能类似：

Trust certificate not found: classpath:certs/ROOTCA.cer

处理：

1. 确认文件存在：

ls src/main/resources/certs

2. 确认打包后在 jar 内：

jar tf target/gm-ssl-client-0.0.1-SNAPSHOT.jar | grep 'certs/'

3. 如果用 file:，确认路径和权限：

ls -l /etc/gmssl/certs/ROOTCA.cer

---

11. 如果 Maven 依赖下载失败

重点依赖：

<com.tencent.kona:kona-crypto:1.0.20>
<com.tencent.kona:kona-pkix:1.0.20>
<com.tencent.kona:kona-ssl:1.0.20>
<com.dtflys.forest:forest-spring-boot-starter:1.8.0>

处理方向：

• 检查 Maven mirror；
• 检查公司代理；
• 检查本地仓库是否损坏；
• 如果公司仓库没有 Kona，需要申请同步。

不要随便升级版本。Forest/OkHttp/Kona 的组合会影响兼容层，升级前要重跑完整握手测试。

---

12. 本篇小结

你已经完成：

1. 确认默认配置；
2. 放置/理解 CA 证书；
3. 知道客户端 KeyStore 何时需要；
4. 跑 mvn test；
5. 打包 jar；
6. 启动联调服务；
7. 打开 Web 页面。

下一篇我们真正发起上传请求，并学习怎么看返回的诊断 JSON。