docs: add API reference and environment variable guide

- docs/api-reference.md: comprehensive API documentation for client and admin endpoints
- docs/env-secrets-guide.md: guide for generating secure keys and tokens

docs/env-secrets-guide.md

@@ -0,0 +1,77 @@
+---
+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 验证逻辑