From 164f98cf33ecd2d4cf9b364c0ca3261380ea5d1c Mon Sep 17 00:00:00 2001 From: zetaloop Date: Sun, 3 May 2026 19:00:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20dev=20README=20?= =?UTF-8?q?=E5=AF=B9=E9=BD=90=20per-domain=20=E6=8B=93=E6=89=91=E4=B8=8E?= =?UTF-8?q?=E5=89=8D=E7=AB=AF=E9=9B=86=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- deploy/dev/README.md | 77 ++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 42 deletions(-) diff --git a/deploy/dev/README.md b/deploy/dev/README.md index 8cccb5d..1c3aa98 100644 --- a/deploy/dev/README.md +++ b/deploy/dev/README.md @@ -4,63 +4,54 @@ - Docker（需要 buildx） - Python 3（构建脚本） +- Git（含 submodule：首次需 `git submodule update --init --recursive`） ## 使用 ```bash cd deploy/dev -# 1. 构建所有微服务镜像 -# 默认 8 并行，可通过环境变量 BAKE_BATCH_SIZE 调整 +# 1. 构建所有镜像（默认 8 并行，可通过 BAKE_BATCH_SIZE 调整） python3 build.py # 2. 启动 docker compose up -d -# 3. 查看状态 -docker compose ps - -# 4. 通过网关访问 -curl http://127.0.0.1:18080/healthz - -# 5. 停止 -docker compose down +# 3. 通过网关访问 +open http://127.0.0.1:18080 ``` -构建脚本会扫描 `app/` 下所有 `api`、`rpc`、`mq`、`adapter` 入口，通过 `docker buildx bake` 并行构建所有服务镜像，生成 `juwan/-:dev`。 +构建脚本扫描 `app/` 下所有 `api`、`rpc`、`mq`、`adapter` 入口和 `frontend/`，通过 `docker buildx bake` 并行构建所有镜像，生成 `juwan/-:dev` 与 `juwan/frontend:dev`。 -端到端接口测试走网关 `http://127.0.0.1:18080`，`18801-18814` 是各服务的直连端口，不经过认证链路。 +前端作为 submodule 接入 compose，通过 envoy 的同源 fallback 路由向浏览器提供，无需独立端口。 -Chat WebSocket 通过网关 `ws://127.0.0.1:18080/ws/chat` 访问。WebTransport 使用 `18443/udp` 的 `/wt/chat` 入口。 - -如需只启动部分服务： - -```bash -docker compose up -d postgres redis snowflake player-rpc player-api -``` +Chat WebSocket 通过 `ws://127.0.0.1:18080/ws/chat` 访问。WebTransport 使用 `18443/udp` 的 `/wt/chat`。 ## 端口映射 -| 服务 | 宿主机端口 | -| ---------------- | ---------------- | -| PostgreSQL | 15432 | -| Redis | 16379 | -| Kafka | 19092 | -| Envoy Gateway | 18080 | -| 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, 18443/udp | -| review-api | 18811 | -| dispute-api | 18812 | -| notification-api | 18813 | -| search-api | 18814 | +| 服务 | 宿主机端口 | 说明 | +| ---------------- | ---------------- | ---------------------------------- | +| 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 互访。 ## 环境变量 @@ -74,17 +65,19 @@ docker compose up -d postgres redis snowflake player-rpc player-api | 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` 领取 `XSRF-TOKEN` 和 `XSRF-GUARD`，再在请求头带上 `xsrf-token`。 +写接口需要先 `GET /healthz` 领取 `__Host-XSRF-TOKEN` 和 `__Host-XSRF-GUARD` cookie，再在请求头带上 `xsrf-token`。 注册和密码重置都需要先调验证码接口拿到 `requestId`，再把它放到 `X-Request-Id` 请求头里发后续请求。 -## 数据库初始化 +## 数据库与初始化 -首次启动时 PostgreSQL 会自动执行 `desc/sql/` 下的建表语句。如需重新初始化，删除 volume 后重启： +每个 per-domain PostgreSQL 首次启动时，通过挂载 `desc/sql//` 和 `deploy/dev/fixture/.sql` 自动完成建表与演示数据导入。如需完全重置： ```bash docker compose down -v