证书管理

为 Umoo 平台生成和管理 TLS 证书及 JWT 签名密钥。

概述

umoo cert CLI 命令处理 PKI 操作：

• TLS 证书 — 自签名 CA + 服务器证书，或 ACME 签发的证书（Let's Encrypt、ZeroSSL）
• JWT 密钥 — 用于签署和验证 JWT 令牌的 RSA 密钥对
• 证书续期 — 在到期前自动续期自签名证书

TLS 证书生成

自签名模式

生成私有 CA 和服务器证书：

umoo cert tls generate --mode selfsigned \
  --domain umoo.yun \
  --output-dir ./configs/pki

生成四个文件：

文件	描述
ca.crt	CA 证书（分发给客户端以建立信任）
ca.key	CA 私钥（妥善保管）
server.crt	由 CA 签署的服务器证书
server.key	服务器私钥

选项

参数	默认值	描述
--domain	localhost	证书的域名/CN
--sans	—	附加 SAN，逗号分隔（DNS 名称或 IP）
--validity	365d	服务器证书有效期
--ca-validity	3650d	CA 证书有效期
--output-dir	./configs/pki	输出目录
--force	false	覆盖现有证书

带 SAN 的示例

umoo cert tls generate --mode selfsigned \
  --domain umoo.yun \
  --sans "umoo.internal,10.0.0.1,*.umoo.yun" \
  --validity 730d \
  --output-dir /etc/umoo/pki

ACME 模式（Let's Encrypt）

从 ACME 提供商获取证书：

umoo cert tls generate --mode acme \
  --domain umoo.yun \
  --email admin@example.com \
  --output-dir ./configs/pki

生成：

文件	描述
server.crt	ACME 提供商签发的服务器证书
server.key	服务器私钥

ACME 选项

参数	默认值	描述
--provider	letsencrypt	ACME 提供商预设或目录 URL
--email	—	账户邮箱（必填）
--staging	false	使用测试端点（用于测试）
--challenge	http	验证类型：http 或 dns
--http-port	:80	HTTP-01 验证监听端口
--dns-provider	—	DNS-01 验证的 DNS 提供商（例如 cloudflare）

DNS-01 验证（Cloudflare）

用于通配符证书或端口 80 不可用的情况：

export CF_API_TOKEN=your_cloudflare_api_token

umoo cert tls generate --mode acme \
  --domain "*.umoo.yun" \
  --email admin@example.com \
  --challenge dns \
  --dns-provider cloudflare

TLS 证书续期

在到期前续期自签名证书：

umoo cert tls renew --output-dir ./configs/pki

该命令检查现有证书是否在续期窗口内。如果是，则使用现有 CA 重新生成服务器证书。

参数	默认值	描述
--output-dir	./configs/pki	包含证书文件的目录
--force	false	即使未接近到期也续期
--renew-before	30d	续期阈值（到期时间在此范围内则续期）

自动续期

设置 cron 任务或 systemd 定时器：

# 每天续期，仅在距到期 30 天内才执行
0 3 * * * /usr/local/bin/umoo cert tls renew --output-dir /etc/umoo/pki

证书检查

查看现有证书的详细信息：

# 检查默认服务器证书
umoo cert tls info --output-dir ./configs/pki

# 检查指定证书文件
umoo cert tls info /path/to/cert.pem

输出包括：主题、签发者、SAN、有效期、序列号和密钥用途。

JWT 密钥生成

生成用于 JWT 令牌签名的 RSA 密钥对：

umoo cert jwt generate --output-dir ./configs/jwt

生成：

文件	描述
private.key	用于签署 JWT 的 RSA 私钥
public.key	用于验证 JWT 的 RSA 公钥

参数	默认值	描述
--output-dir	./configs/jwt	输出目录
--key-size	2048	RSA 密钥位数
--force	false	覆盖现有密钥

配置服务器使用这些密钥：

jwt:
  private_key: ./configs/jwt/private.key
  public_key: ./configs/jwt/public.key

设备证书

设备使用 mTLS 客户端证书向平台认证。证书生命周期：

1. 管理员为设备生成认领令牌。
2. 设备 Agent 使用认领令牌连接并提交 CSR（证书签名请求）。
3. 平台 CA 签署 CSR 并返回设备证书。
4. Agent 在后续所有 mTLS 连接中使用该证书。

设备证书自动管理 — 初次认领后不需要手动干预。

安全最佳实践

• 使用受限文件权限（chmod 600）存储 CA 私钥（ca.key）和 JWT 私钥（private.key）。
• 生产环境使用 ACME 模式获取公共信任的证书。
• 设置自动证书续期以避免服务中断。
• RSA 密钥大小至少使用 2048 位（高安全环境建议 4096 位）。
• 定期轮换 JWT 密钥，生成新密钥并更新服务器配置。