Appearance
本地开发与构建
前置条件
- Node.js、pnpm
- MySQL（ZenStack / 应用数据）
- Redis（Sys 登录会话等）
环境文件
backend/.env：由backend/.env.example复制。至少配置DATABASE_URL、JWT_SECRET（网关与 Sys 必须一致）、REDIS_*、SYS_SERVICE_URL、ACC_SERVICE_URL。frontend/.env：由frontend/.env.example复制，例如VITE_API_BASE_URL指向网关（默认http://localhost:3000）。
数据库与 ZenStack
在 backend/ 目录：
bash
pnpm run zen:generate
pnpm run zen:pushzen:generate：根据zenstack/schema.zmodel生成客户端与类型。zen:push：将 schema 同步到数据库（生产环境请改用迁移策略）。
常用命令（仓库根目录）
| 命令 | 说明 |
|---|---|
pnpm install | 安装 workspace 依赖 |
pnpm dev | 并行启动 gateway、sys、acc、Vite 前端 |
pnpm dev:backend | 仅三后端 |
pnpm dev:web | 仅前端 |
pnpm build | 后端 build + 前端 build + VitePress 文档 build |
pnpm docs:dev / pnpm --filter taskflow-docs dev | 仅启动本 VitePress 文档站（5174，与前端 5173 区分） |
开发时浏览器访问 前端端口（默认 5173），由 Vite 将 /api 代理到网关，再由网关转发 Sys / Acc。
API 文档（Knife4j）
后端 Sys / Acc 启动后（pnpm dev:backend）可打开：
- 推荐（Sys / Acc 左上角切换）：http://localhost:3000/doc.html
- 说明页：http://localhost:3000/api-doc
- 仅 Sys：http://localhost:3001/doc.html · 仅 Acc：http://localhost:3002/doc.html
详见 API 文档（Knife4j）。生产环境请设 SWAGGER_ENABLED=false。
文档站点
文档开发服务器固定为 5174（在 docs/.vitepress/config.ts 的 vite.server.port），避免与前端 pnpm dev:web 的 5173 冲突。
bash
pnpm docs:dev
# 或
pnpm --filter taskflow-docs dev浏览器打开 http://localhost:5174。顶栏 指南 含 docs/guide/ 全部分组侧栏；发版签字 为 docs/ci/ 可打印签字表。
构建与预览静态站点：
bash
pnpm docs:build
pnpm docs:preview预览默认使用 4174（vite.preview.port），与前端 vite preview 常用 4173 错开。
生产（Docker 前端镜像）：文档与主站打在同一 nginx 根目录，访问路径为 /docs/（构建时设置 VITEPRESS_BASE=/docs/，见 deploy/docker/Dockerfile.frontend）。本地 pnpm docs:build 仍为站点根路径 /，便于单独预览静态文件。
独立文档端口（如 external-dbs 中 docs 服务映射 7001）：与 web 使用同一镜像 taskflow-frontend。镜像内构建两套 VitePress：一套 base /docs/ 挂主站同域，一套 base / 放在 /usr/share/nginx/docs-standalone；docs 容器通过 /opt/taskflow/nginx-entrypoint-docs.sh 只启用第二套（见 deploy/docker/Dockerfile.frontend）。