chore: initialize clean metapi repository

docs/faq.md

@@ -0,0 +1,131 @@
+# ❓ 常见问题（FAQ）
+
+[返回文档中心](./README.md)
+
+---
+
+## 部署相关
+
+### Q: 启动后无法访问管理后台
+
+**A:** 排查步骤：
+
+1. 确认容器正常运行：`docker compose ps`
+2. 确认端口映射正确：`docker compose logs | grep listening`
+3. 检查防火墙是否放行了端口（默认 4000）
+4. 如果使用反向代理，确认代理配置正确
+
+### Q: 登录失败，提示令牌无效
+
+**A:** 检查 `AUTH_TOKEN` 是否与部署环境一致。注意：
+
+- 使用 `.env` 文件时，确认文件路径正确
+- 不要混用 `.env.example` 的默认值
+- 环境变量中的值不需要加引号
+
+### Q: Docker Compose 启动报错 `AUTH_TOKEN is required`
+
+**A:** 使用了 `${AUTH_TOKEN:?}` 语法，需要先设置环境变量：
+
+```bash
+export AUTH_TOKEN=your-token
+export PROXY_TOKEN=your-proxy-token
+docker compose up -d
+```
+
+或使用 `.env` 文件。
+
+---
+
+## 代理相关
+
+### Q: 下游客户端提示 401 / 403
+
+**A:** 排查：
+
+- 确认使用的是 `PROXY_TOKEN`（代理令牌），而非 `AUTH_TOKEN`（管理令牌）
+- 确认反向代理正确透传了 `Authorization` 请求头
+- 检查是否设置了 `ADMIN_IP_ALLOWLIST` 限制了访问
+
+### Q: `GET /v1/models` 返回空列表
+
+**A:** 可能原因：
+
+1. 未添加任何站点或账号
+2. 账号处于 `unhealthy` 状态 — 在账号管理页面检查并刷新
+3. 未同步 Token — 在 Token 管理页面点击「同步」
+4. 模型未发现 — 手动触发模型刷新
+
+### Q: 非流式正常，但流式输出异常（卡住、乱码、截断）
+
+**A:** 几乎都是反向代理配置问题。请确认：
+
+1. Nginx：添加 `proxy_buffering off;`
+2. 未改写 `text/event-stream` Content-Type
+3. 无 CDN 或中间层缓存 SSE 响应
+
+完整 Nginx 配置参考 [部署指南](./deployment.md#nginx)。
+
+### Q: 某模型显示可用，但实际调用失败
+
+**A:** 在管理后台的「模型测试器」中直测该模型，查看具体失败原因：
+
+- **上游账号状态异常**：账号凭证过期或被禁用
+- **通道处于冷却期**：近期该通道请求失败，系统自动冷却（默认 10 分钟）
+- **上游模型下线**：上游站点已移除该模型
+- **余额不足**：对应账号余额已耗尽
+
+### Q: 请求延迟很高
+
+**A:** 排查方向：
+
+- 在代理日志中查看具体延迟分布
+- 检查是否因冷却导致使用了较远/较慢的上游
+- 调整路由权重，降低 `COST_WEIGHT`、提高成功率高的通道优先级
+
+---
+
+## 签到相关
+
+### Q: 签到一直失败
+
+**A:** 可能原因：
+
+- 上游站点不支持签到功能
+- 账号凭证已过期（系统会尝试自动重登录）
+- 站点接口变更 — 检查 Metapi 是否为最新版本
+
+### Q: 签到成功但奖励显示为 0
+
+**A:** 部分站点的签到接口不返回奖励金额。Metapi 会尝试从收入日志推算奖励，但可能存在延迟。
+
+---
+
+## 数据相关
+
+### Q: 数据迁移怎么做
+
+**A:** 两种方式：
+
+1. **应用内导入导出**（推荐）：在管理后台 → 导入/导出 页面操作，支持选择性导出
+2. **目录迁移**：直接拷贝 `data/` 目录到新环境
+
+### Q: 如何清理历史数据
+
+**A:** 代理日志和签到日志会持续增长。在管理后台对应页面可以清理历史记录。
+
+### Q: 开源发布时如何避免泄露敏感信息
+
+**A:**
+
+- 确认 `.gitignore` 包含 `.env`、`data/`、`tmp/`
+- 发布前执行一次密钥轮换（上游账号密码、通知 SMTP、Webhook 地址）
+- 使用全新仓库或清理 Git 历史后再公开
+- 检查备份 JSON 文件中是否包含凭证
+
+---
+
+## 更多帮助
+
+- [提交 Issue](https://github.com/cita-777/metapi/issues) — 报告 Bug 或提出建议
+- [文档中心](./README.md) — 查看所有文档