豆芽 OPS 网站项目手册
了解本站实际架构、交付范围和维护职责，并按角色进入开发、内容、接口与运维文档。
适用范围
本手册面向维护当前仓库的开发者、内容编辑和部署负责人。本站将工具、运维场景、知识、项目与层级文档连接起来，提供公开检索和后台内容管理。项目处于 BETA；页面中出现某项工具或场景，不代表该工具已在本站部署，也不代表操作方案已在读者的环境演练。
架构与交付件
公开站使用 Nuxt 3、Vue 3 与 TypeScript，公开内容页面使用 SSR；管理页面通过同源 API 代理访问 Go/Gin 服务。PostgreSQL 是核心数据存储，Redis 支撑 Session、验证码与限流等能力。数据库查询当前由仓库层手写 SQL 实现，不能将规划中的 sqlc 生成过程当作安装必需步骤。
仓库交付 api/openapi.yaml、数据库迁移、内容包、验证脚本和单机 Compose 发布栈。单机部署便于复现，但不是数据库高可用架构。公开项目页列出的监控、日志、CI/CD 场景供扩展参考，部署负责人仍需另行设计接入。
按角色阅读
- 开发者先读本地开发，再检查配置与安全。
- 内容编辑使用内容发布流程，以后台和内容包维护文章关系及文档树。
- 接口调用方阅读API 速查，完整字段以仓库契约为准。
- 部署负责人阅读生产运维和发布检查清单。
- 遇到异常从常见问题按症状定位，避免直接重建数据。
最小进入条件
阅读公开内容不需要管理员凭据。启动开发环境需要 Go、Node.js、Docker Compose 及可写的开发数据库；编辑内容需要已初始化的管理员和相应权限。生产环境必须使用独立密钥与账号，不能复用示例配置。配置文件、Cookie、CSRF Token、MFA 密钥、数据库连接串均不得复制到文章或问题截图中。
在已启动的本地 API 上，可先进行无写入检查：
curl --fail-with-body http://127.0.0.1:8080/health/ready
curl --fail-with-body 'http://127.0.0.1:8080/api/v1/projects?page=1&page_size=20'验收和交接
开发完成至少应保留类型检查、构建和测试结果；内容完成应检查公开详情、文档父子路径、搜索结果和安全链接；部署完成还要记录镜像标签、迁移版本、备份位置与目标环境冒烟结果。健康检查通过不能证明登录、发布、备份恢复或公网 DNS 都可用。
停止与恢复边界
目标数据库不明、同 Slug 内容冲突、缺失备份、生产密钥仍是占位符或证书不匹配时，应停止写入和发布，先由负责人确认。不要使用迁移回退或数据库恢复来撤销普通文案错误；应保留当前文本，再通过管理接口修订。数据库恢复会覆盖数据，只能在明确停写窗口和恢复点后执行。