---
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 验证逻辑