本地开发环境搭建

本章目标:

1. 知道本地最小开发栈起哪些进程、为什么只起这些、各自端口
2. 按正确顺序把 postgres → deer-flow 引擎 → acdm-backend → 前端跑起来
3. 理解本地 dev 的鉴权是怎么"无后门"地顶替生产 forward_auth 的

TL;DR

本地开发刻意做了"A 方案最小集":docker-compose.dev.yml 只起一个 postgres(端口 5435),Caddy/Nextcloud/Redis/auth-mock 一律不起 —— 因为生产已有这些基础设施可复用,本地 deer-flow checkpointer 用 SQLite 就够。启动顺序是 postgres → deer-flow gateway/runtime → acdm-backend → 前端 pnpm dev。dev 鉴权走 Authorization: Bearer dev-token 直通后端,与生产同一条校验路径,只是省掉 Caddy forward_auth 这一跳。

Overview(为什么本地不起全套)

直觉做法是"本地 docker-compose 把生产那套全 mirror 一遍",但 a-cdm 2026-04-18 明确否决了,理由写在 docker-compose.dev.yml:3-22:

1. 生产 172.20.21.28 已有 platform-gateway / platform-db / auth-api,本地再起一套是重复维护;
2. Nextcloud 直连 team.r7.chinasoftinc.com 的实验路径(VPN 开着即可),不必本地起;
3. deer-flow 本地 checkpointer 用 SQLite 即可,不必 Redis;
4. auth 走 Authorization: Bearer dev-token 直通后端,forward_auth 留到生产。

所以本地栈是"够开发就行"的最小集 —— 一个 postgres,其余进程直接在宿主机用各自的 dev server 跑(uvicorn --reload / pnpm dev / make dev),热更新更快、调试更直接。

本地最小栈:postgres

docker-compose.dev.yml 只有一个 service:

项	值	说明	Source
image	postgres:16-alpine	复用本机已有 image(knowledge-compiler-db 用过)	docker-compose.dev.yml:38
容器名	acdm-dev-postgres	—	docker-compose.dev.yml:39
端口	5435:5432	dev 用 5435 避让已在跑的 5433(knowledge-compiler-db)/ 5434(meeting-v011)	docker-compose.dev.yml:46-49
账密库	acdm / acdm / acdm	POSTGRES_USER/PASSWORD/DB	docker-compose.dev.yml:42-44
编码	UTF8 + locale C	POSTGRES_INITDB_ARGS	docker-compose.dev.yml:45
健康检查	pg_isready 每 5s	retries 10	docker-compose.dev.yml:53-57

一键起:docker compose -f docker-compose.dev.yml up -d(docker-compose.dev.yml:24-25)。注意这套 postgres 同时承担 acdm-backend 业务数据和 deer-flow checkpointer(docker-compose.dev.yml:11),不像生产分多 DB。

启动顺序(分阶段)

docker-compose.dev.yml:10-18 把启动分成三阶段,依赖关系决定了顺序:

1. postgres:docker compose -f docker-compose.dev.yml up -d,等 healthcheck 通过。
2. deer-flow 引擎(Step 1b):gateway(8001)+ runtime(2024),同一镜像不同启动命令。引擎自带 make 工作流:make dev 起全部 dev 服务热更新、make dev-pro 用 Gateway 模式(无 LangGraph server)、make stop 停全部(deer-flow/Makefile:30-44)。本地 checkpointer 用 SQLite(checkpoints.db),不依赖 Redis。
3. acdm-backend(Step 2):uvicorn --reload,监听 127.0.0.1:8002(acdm-backend/README.md:4)。容器内启动命令 alembic upgrade head && uvicorn app.main:app(见生产 acdm-backend/Dockerfile),本地直接跑 uvicorn 即可。DATABASE_URL 本地指向 localhost:5435(生产指向 platform-db:5432,见 acdm-backend/compose.yml:14)。
4. 前端:pnpm dev(= next dev --turbo,deer-flow/frontend/package.json:10)起 :3000,通过 next.config rewrites 把 /api/* 反代到本地后端/引擎。

本仓 CLAUDE.md 引用了 docs/runbooks/dev-setup.md 描述"5 终端 + 一键停"的完整本地编排;本章只覆盖代码与编排文件能证实的部分,完整 5 终端流程以该 runbook 为准。

dev 鉴权:无后门地顶替 forward_auth

a-cdm 的铁律是"dev 与 prod 同一条路径,无后门"(CLAUDE.md:14)。本地没有 Caddy,forward_auth 这一跳由谁补?答案是前端 proxy.ts 自己解 cookie 注入 header,后端校验逻辑完全不变:

• 生产:Caddy forward_auth → acdm-backend:8002/auth/verify,verify 通过后 Caddy 注入 X-Auth-User-Id 等头给上游。
• 本地:前端 deer-flow/frontend/src/proxy.ts 从 acdm_session cookie 解 JWT payload,把 X-Auth-User-Id / X-Auth-User-Role 注入到发往 /api/langgraph/* 与 /api/memory/* 的请求;acdm-backend 自身 API 走 Authorization: Bearer dev-token 直通(docker-compose.dev.yml:8)。

关键点:后端的鉴权/授权代码两边一模一样,本地只是把"谁来注入 header"从 Caddy 换成前端 proxy,没有任何"dev 跳过校验"的分支。这条机制的细节在"proxy 鉴权守卫"章。

Configuration(本章相关)

配置	dev 值	prod 值	Source
postgres 端口	5435	5433 / platform-db:5432	docker-compose.dev.yml:48
DATABASE_URL	localhost:5435/acdm	platform-db:5432/acdm	acdm-backend/compose.yml:14
checkpointer	SQLite checkpoints.db	postgres aegra DB	docker-compose.dev.yml:7
auth	Bearer dev-token 直通	Caddy forward_auth	docker-compose.dev.yml:8
acdm-backend 端口	127.0.0.1:8002(--reload)	Caddy /api/acdm/*	acdm-backend/README.md:4

Common Pitfalls / 实战 Tips

• 端口冲突:dev 用 5435 不是 5433,因为本机常并行跑 knowledge-compiler-db(5433)和 meeting-v011(5434),用错端口会连到别的库(docker-compose.dev.yml:47)。
• 多 worktree 并行:多个 worktree 同时开发要协调端口、memory junction,SOP 见项目 docs/runbooks/multi-worktree.md(红线规定 worktree 必须建在 <repo>/.claude/worktrees/<name>/)。
• make config 不覆盖已有配置:deer-flow 引擎的 make config 若 config 已存在会 abort,要合并上游新字段用 make config-upgrade(deer-flow/Makefile:35-36)。
• 本地改 .env 后:dev 用 uvicorn --reload 会自动重载;但容器化场景改 .env 必须 up -d --force-recreate,restart 不重读 .env(CLAUDE.md:14,lessons L88)。

References

• docker-compose.dev.yml:1-58 — 本地最小栈定义 + 决策背景注释(本章主源)
• acdm-backend/compose.yml:1-39 — 生产 compose,对照看 dev/prod DATABASE_URL 差异
• acdm-backend/README.md:1-5 — acdm-backend dev 端口与职责
• deer-flow/frontend/package.json:6-21 — 前端 dev/build/test scripts
• deer-flow/Makefile:1-44 — 引擎统一开发命令(dev/dev-pro/stop/config-upgrade)
• deer-flow/frontend/src/proxy.ts — dev 鉴权 header 注入(顶替 forward_auth)

Related Pages

Page	Relationship
系统整体架构	本章是该章 dev 拓扑的启动落地
proxy 鉴权守卫与 API 反代	本章 dev 鉴权注入的实现细节在该章
鉴权与授权双层体系	本章"无后门"原则的完整校验链在该章
CI/CD 与生产部署运维	本章 dev compose 对照该章的生产编排
环境变量、凭据与降级开关	本章 .env 与 --force-recreate 在该章详解