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]>
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# 开发环境运行手册
|
|
|
|
## 前置
|
|
|
|
- Node.js ≥ 24(当前开发机 24.15)、pnpm 11(`packageManager` 已锁)、Docker。
|
|
- 端口:web 5180、API 4380、PG 55433。本机 3000/5175/5176/55432 已被其他项目占用,不要改用。
|
|
|
|
## 首次启动
|
|
|
|
```sh
|
|
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`。
|
|
|
|
## 验证
|
|
|
|
```sh
|
|
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]`;若发现明文,属于缺陷。
|