# 本地开发环境

## 前置条件

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

## 使用

```bash
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` 自动完成建表与演示数据导入。如需完全重置：

```bash
docker compose down -v
docker compose up -d
```