duoqi-api/docs/env-secrets-guide.md

title	date	tags
环境变量密钥生成指南	2026-04-10	duoqi-api devops security

环境变量密钥生成指南

duoqi-api 的 .env 中有多个需要生成的密钥/Token，本文档记录各字段的生成方式与注意事项。

JWT_SECRET

用于 JWT 签名与验证（@fastify/jwt），==必须==使用密码学安全的随机值。

# 推荐：openssl
openssl rand -base64 32

# 或用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# 或 hex 格式
openssl rand -hex 32

[!warning] 安全要点

• 32 字节（256 位）是常见选择
• 泄露后可伪造任意用户 token
• 更换后所有已颁发的 token 失效（用户全部掉线）
• ==不要==提交到 Git，仅存在于 .env 文件

ADMIN_TOKEN

管理端鉴权 Token，src/middleware/admin-auth.ts 中直接字符串比对。

openssl rand -hex 16

也可以自定义强密码，只要够长且不可预测。

[!tip] 生产环境建议 当前实现是明文比对，生产环境可考虑改为哈希比对（如 bcrypt），避免 .env 泄露时直接暴露 Token。

HUAWEI_CLIENT_SECRET

华为开发者平台提供，不可自行生成。在 华为开发者联盟 应用详情页获取。

OSS_ACCESS_KEY_SECRET

阿里云控制台提供。在 RAM 访问控制 中创建 AccessKey 时获取。

[!danger] 严禁

• 将 AccessKey 提交到 Git
• 使用主账号 AccessKey（应创建 RAM 子账号并最小授权）

快速生成所有密钥

一键生成 JWT_SECRET 和 ADMIN_TOKEN：

echo "JWT_SECRET=$(openssl rand -base64 32)"
echo "ADMIN_TOKEN=$(openssl rand -hex 16)"

将输出复制到 .env 文件即可。

---

相关文件：

• .env.example — 环境变量模板
• src/utils/config.ts — Zod 校验与启动 fail-fast
• src/middleware/auth.ts — JWT 验证逻辑
• src/middleware/admin-auth.ts — Admin Token 验证逻辑