umtandClaude Fable 5.1
b22c440139
- pnpm workspace: apps/{web,server}, packages/{contracts,db,domain,adapters,tasks,agent,testkit}
- server: Hono + zod-openapi, API Key auth with scopes, redacting pino logger, SSE event bus with replay, worker heartbeat
- db: Kysely + pg, file migrator, 0001_init (settings/api_key/audit_event/outbox_event)
- web: React Router 7 SPA console shell with 12 workspace placeholders, uhd_web tokens/ui/guard scripts
- docs: ADR-001 (Node over Deno), dev runbook, design system rules
Co-Authored-By: Claude Fable 5.1 <[email protected]>
2.2 KiB
2.2 KiB
开发环境运行手册
前置
- Node.js ≥ 24(当前开发机 24.15)、pnpm 11(
packageManager已锁)、Docker。 - 端口:web 5180、API 4380、PG 55433。本机 3000/5175/5176/55432 已被其他项目占用,不要改用。
首次启动
cp .env.example .env # 按需修改;server 与 db 脚本都读仓库根 .env
pnpm db:up # 起 postgres:16-alpine(docker-compose.dev.yml,数据卷 umt-pg-data)
pnpm install
pnpm db:migrate # 执行 packages/db/migrations 下全部迁移
pnpm dev # 同时起 server(4380)与 web(5180)
单独起:pnpm dev:server(默认 --role all,API + worker 同进程)、pnpm dev:web。
验证
curl localhost:4380/api/v1/health
# 开发模式可用 .env 的 DEV_ADMIN_KEY 作 admin
curl -N -H "Authorization: Bearer umt-dev-admin-key" "localhost:4380/api/v1/events?after=0"
- OpenAPI:http://localhost:4380/api/openapi.json,文档页 http://localhost:4380/api/docs
- 控制台:http://localhost:5180,右上角钥匙按钮设置 API Key(存 localStorage
umt-api-key)
常用命令
| 命令 | 作用 |
|---|---|
pnpm run ci |
typecheck + lint + test + check:tokens + build,提交前必须全绿。注意 pnpm ci 在 pnpm 11 是内置的 clean-install 命令,不会执行本脚本 |
pnpm format |
biome 自动修复格式与 import 排序 |
pnpm db:reset |
清空 public schema 并重新迁移(生产环境拒绝执行) |
pnpm --filter @umt/web gen:tokens |
改了 app.css 后重新生成 token 登记表 |
pnpm --filter @umt/server start |
运行 pnpm build 产出的 apps/server/dist/main.js |
进程角色
node dist/main.js --role api|worker|all。all 下 worker 心跳会发布到进程内事件总线,SSE 可见;分进程部署时事件总线需改为 PG 投影(W2)。
排障
配置无效:按提示检查.env,SECRET_MASTER_KEY至少 16 字符,DATABASE_URL必须是 postgres://。- health 返回
db: "down":docker compose -f docker-compose.dev.yml ps看容器健康状态。 - 日志中的 passkey/token/cookie/authorization/password 字段与 URL query 参数会被替换为
[REDACTED];若发现明文,属于缺陷。