本地开发与环境初始化
从工具链、数据库迁移到管理员初始化和前后端启动，建立可验证的本地开发环境。
环境前提
在仓库根目录操作。server/go.mod 要求 Go 1.25.0 工具链，web/package.json 要求 Node.js 不低于 22.12.0。准备 npm、Make、Docker Compose；迁移需要本机 PostgreSQL 客户端或 Docker。开发 Compose 使用 PostgreSQL 17 和 Redis 7，默认仅绑定回环地址的 5432 与 6379。
先确认没有其他项目占用这些端口。不要同时启动 Compose 的 app profile 和本机 API/Web，两者默认占用 8080/3000。已有 .env 时保留原文件，不运行下面的复制步骤覆盖它。
安装与配置
仅首次创建开发配置：
cp .env.example .env
cd web
npm ci
cd ..检查 .env 中数据库、Redis 和端口是否指向本项目开发环境。Make 会载入根目录 .env；直接执行 Go 或 Node 脚本不会自动得到这些变量。示例账号仅用于本地开发，本文不复制密码；真实凭据不得写入 Git 或分享日志。
依赖安装以锁文件为准，不为解决一次启动问题随意升级全部包。首次拉取依赖需要网络；离线或代理受限时先解决依赖来源，不能把缺失依赖误判为应用代码错误。若修改了依赖文件，要将锁文件变化和安装验证一起交付。
初始化数据和管理员
下列步骤会启动基础设施、修改数据库结构和创建管理员，确认目标后执行：
make infra-up
make migrate-up
make admin-provision迁移成功应显示已应用或跳过的版本数量。不要为了“清空错误”运行 make migrate-down：该目标会回退全部已跟踪迁移。已有数据库初始化异常时，先保留日志并核对连接、迁移状态和数据库归属。
启动前后端
分别在两个终端、仓库根目录运行：
make api-devmake web-dev公开站默认在本机 3000，后台入口为 /admin/login。如 API 的 8080 已被其他应用占用，可使用 make api-dev HTTP_ADDRESS=127.0.0.1:8081，并以 NUXT_API_ORIGIN=http://127.0.0.1:8081 make web-dev 启动前端。只修改 API 监听端口不会自动更新前端代理。
最小验收
curl --fail-with-body http://127.0.0.1:8080/health/live
curl --fail-with-body http://127.0.0.1:8080/health/ready
make check-ops-content非默认端口需同步替换检查地址。live 仅说明进程存活；ready 应确认 PostgreSQL 可用，Redis 异常会标记降级。打开首页和后台，验证登录后再进入 /admin/security 绑定并验证 TOTP；新账号并不会自动开启动态验证码。
新建空库尚无内容时，目录为空不是启动失败。先确认公开接口可以返回合法的空列表，再进行内容初始化。提交修改前运行完整验证，若失败，应记录第一处错误和相关版本，不用新增样例数据掩盖问题。
停止、恢复和下一步
用各终端的 Ctrl-C 停止自己启动的 API/Web。停止基础设施前确认没有其他任务共用本项目 Compose；make infra-down 不带删除卷参数，不要追加 -v 清除数据。开发配置改错时恢复已知配置并重启对应服务，数据库错误先备份再判断，不盲目重新迁移。