Wang Zhuoxuan
2dd5f18822
- docs/api-reference.md: comprehensive API documentation for client and admin endpoints - docs/env-secrets-guide.md: guide for generating secure keys and tokens
78 lines
2.0 KiB
Markdown
78 lines
2.0 KiB
Markdown
---
|
||
title: 环境变量密钥生成指南
|
||
date: 2026-04-10
|
||
tags:
|
||
- duoqi-api
|
||
- devops
|
||
- security
|
||
---
|
||
|
||
# 环境变量密钥生成指南
|
||
|
||
duoqi-api 的 `.env` 中有多个需要生成的密钥/Token，本文档记录各字段的生成方式与注意事项。
|
||
|
||
## JWT_SECRET
|
||
|
||
用于 JWT 签名与验证（`@fastify/jwt`），==必须==使用密码学安全的随机值。
|
||
|
||
```bash
|
||
# 推荐：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` 中直接字符串比对。
|
||
|
||
```bash
|
||
openssl rand -hex 16
|
||
```
|
||
|
||
也可以自定义强密码，只要够长且不可预测。
|
||
|
||
> [!tip] 生产环境建议
|
||
> 当前实现是明文比对，生产环境可考虑改为哈希比对（如 `bcrypt`），避免 `.env` 泄露时直接暴露 Token。
|
||
|
||
## HUAWEI_CLIENT_SECRET
|
||
|
||
华为开发者平台提供，不可自行生成。在 [华为开发者联盟](https://developer.huawei.com/) 应用详情页获取。
|
||
|
||
## OSS_ACCESS_KEY_SECRET
|
||
|
||
阿里云控制台提供。在 [RAM 访问控制](https://ram.console.aliyun.com/) 中创建 AccessKey 时获取。
|
||
|
||
> [!danger] 严禁
|
||
> - 将 AccessKey 提交到 Git
|
||
> - 使用主账号 AccessKey（应创建 RAM 子账号并最小授权）
|
||
|
||
## 快速生成所有密钥
|
||
|
||
一键生成 `JWT_SECRET` 和 `ADMIN_TOKEN`：
|
||
|
||
```bash
|
||
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 验证逻辑
|