juwan-backend/deploy/dev

本地开发环境

前置条件

• Docker（需要 buildx）
• Python 3（构建脚本）
• Git（含 submodule：首次需 git submodule update --init --recursive）

使用

cd deploy/dev

# 1. 构建所有镜像（默认 8 并行，可通过 BAKE_BATCH_SIZE 调整）
python3 build.py

# 2. 启动
docker compose up -d

# 3. 通过网关访问
open http://127.0.0.1:18080

构建脚本扫描 app/ 下所有 api、rpc、mq、adapter 入口和 frontend/，通过 docker buildx bake 并行构建所有镜像，生成 juwan/<service>-<type>:dev 与 juwan/frontend:dev。

前端作为 submodule 接入 compose，通过 envoy 的同源 fallback 路由向浏览器提供，无需独立端口。

Chat WebSocket 通过 ws://127.0.0.1:18080/ws/chat 访问。WebTransport 使用 18443/udp 的 /wt/chat。

端口映射

服务	宿主机端口	说明
Envoy Gateway	18080	浏览器入口，/api/*、/ws/*、前端静态都从这里出
Redis	16379	共享会话与验证码
MongoDB	27017	chat 消息持久化
Kafka	19092	email-mq 任务队列
ratelimit	18081, 16070	限流服务
users-api	18801	直连调试入口，不经认证链路
player-api	18802
game-api	18803
shop-api	18804
order-api	18805
wallet-api	18806
community-api	18807
objectstory-api	18808
email-api	18809
chat-api	18810, 18889, 18443/udp
review-api	18811
dispute-api	18812
notification-api	18813
search-api	18814

11 个 per-domain PostgreSQL（users-db、player-db、game-db、shop-db、order-db、wallet-db、community-db、review-db、dispute-db、notification-db、search-db）和 frontend 容器不暴露宿主端口，仅在 compose 内网通过 DNS 互访。

环境变量

编辑 .env 修改数据库密码、Kafka 地址等。默认值可直接用于本地开发。

管理员账户通过环境变量配置，users-rpc 启动时自动初始化：

变量	说明	默认值
ADMIN_USERNAME	管理员用户名	admin
ADMIN_PASSWORD	管理员密码	admin123
ADMIN_EMAIL	管理员邮箱	admin@juwan.dev

默认 admin 固定 ID 100000，拥有消费者、打手、店主三种身份全部开通，并预置了店铺、服务、钱包、帖子等演示数据，可直接用于完整链路联调。

认证

登录和注册通过 users-api 下发 JToken Cookie。envoy-gateway 负责 JWT 校验并注入认证头，authz-adapter 做会话态二次校验，后端服务只消费 x-auth-user-id 等头。

写接口需要先 GET /healthz 领取 __Host-XSRF-TOKEN 和 __Host-XSRF-GUARD cookie，再在请求头带上 xsrf-token。

注册和密码重置都需要先调验证码接口拿到 requestId，再把它放到 X-Request-Id 请求头里发后续请求。

数据库与初始化

每个 per-domain PostgreSQL 首次启动时，通过挂载 desc/sql/<domain>/ 和 deploy/dev/fixture/<domain>.sql 自动完成建表与演示数据导入。如需完全重置：

docker compose down -v
docker compose up -d