126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
# 本机容器化联调教程
|
||
|
||
这套方案的目标是：**Windows 只负责编辑源码和运行微信开发者工具；PostgreSQL、Redis、Node.js/NestJS、Prisma 都运行在 Linux 容器中。** 因此本机行为尽量贴近未来 Linux 服务器，避免把 Windows 的 Node、数据库服务或路径习惯带进部署产物。
|
||
|
||
## 先理解两种 Compose 运行方式
|
||
|
||
| 目的 | 命令 | 特性 |
|
||
| --- | --- | --- |
|
||
| 日常开发、改代码自动重载 | `docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build` | 源码挂载进 Linux 开发容器，NestJS 热重载 |
|
||
| 发布前模拟 | `docker compose up -d --build` | 使用 `docker/Dockerfile` 的多阶段生产构建，不挂载源码 |
|
||
|
||
两种方式共用 PostgreSQL、Redis、迁移文件和 `.env`；不要同时启动它们。日常使用第一种，准备交付或部署前再使用第二种。
|
||
|
||
> Windows 要运行 `node:alpine`、`postgres:alpine` 这类 Linux 镜像，Docker Desktop 底层必须使用 **WSL 2、Hyper-V 或 Docker VMM** 之一。你不需要在 WSL 里写代码或打开 Ubuntu；它只是 Docker 的 Linux 运行底座。若完全不允许这些虚拟化能力，就只能改用远程 Linux 测试机，无法在 Windows 本机运行 Linux Compose。
|
||
|
||
## 一次性安装
|
||
|
||
1. 在 BIOS/UEFI 确认开启 CPU 虚拟化（Intel VT-x / AMD-V）。
|
||
2. 以管理员身份打开 PowerShell，执行 `wsl --install`；已安装时执行 `wsl --update`，按提示重启。
|
||
3. 安装 Docker Desktop for Windows，首次启动时选择 **Use WSL 2 instead of Hyper-V**。无需在 WSL 内安装 Node、PostgreSQL 或 Redis。
|
||
4. 重启 Docker Desktop 后，在普通 PowerShell 验证：
|
||
|
||
```powershell
|
||
docker version
|
||
docker compose version
|
||
```
|
||
|
||
安装依据见 [Docker Desktop for Windows 官方文档](https://docs.docker.com/desktop/setup/install/windows-install/) 与 [WSL 2 后端说明](https://docs.docker.com/desktop/features/wsl/)。
|
||
|
||
## 启动后端联调环境
|
||
|
||
以下命令均在 `G:\wordcloud_wechat\wxmp_backend` 执行。
|
||
|
||
1. 创建只属于本机的配置文件（该文件被 Git 忽略）：
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
2. 打开 `.env`，至少改成下列本机联调值。不要提交 `.env`，真实微信密钥也不要放入前端。
|
||
|
||
```dotenv
|
||
NODE_ENV=development
|
||
APP_PORT=3090
|
||
JWT_SECRET=dev-only-change-this-to-a-long-random-string
|
||
WX_APPID=local-dev-appid
|
||
WX_SECRET=local-dev-secret
|
||
WX_MOCK_LOGIN=1
|
||
```
|
||
|
||
`DATABASE_URL` 和 `REDIS_URL` 可保持示例值：Compose 会在容器内自动改为 `postgres`、`redis` 服务地址。
|
||
|
||
3. 首次先拉取所有公开测试镜像，再构建并启动开发环境：
|
||
|
||
```powershell
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml pull
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
|
||
```
|
||
|
||
预期 `postgres`、`redis`、`app` 都是 running/healthy。查看后端实时日志：
|
||
|
||
```powershell
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f app
|
||
```
|
||
|
||
4. 导入 R1 商品初始数据（只需首次，或想恢复演示数据时执行）：
|
||
|
||
```powershell
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec app npm run prisma:seed
|
||
```
|
||
|
||
5. 在浏览器检查：
|
||
|
||
- `http://127.0.0.1:3090/docs`：Swagger 接口页
|
||
- `http://127.0.0.1:3090/api/products`：R1 商品列表 JSON
|
||
|
||
修改 `src/` 或 `prisma/` 后，开发 Compose 的 `app` 会热重载；变更依赖或 Dockerfile 后重新执行 `up -d --build`。停止环境用 `docker compose -f docker-compose.yml -f docker-compose.dev.yml down`。这不会删除数据库数据卷；需要完全清空数据时才使用 `down -v`。
|
||
|
||
## 微信开发者工具：打开哪里、怎样看到页面
|
||
|
||
应导入 **前端项目根目录**：`G:\wordcloud_wechat\wechat_wc`。
|
||
|
||
不要导入工作区总目录 `G:\wordcloud_wechat`，也不要直接导入 `dist`。原因是前端根目录的 `project.config.json` 中已经声明 `miniprogramRoot: "dist/"`；开发者工具从该根目录读取项目配置，再把 `dist` 当作实际小程序输出。
|
||
|
||
首次操作如下：
|
||
|
||
1. 在一个 PowerShell 窗口进入前端目录，安装依赖并创建本机环境文件：
|
||
|
||
```powershell
|
||
cd G:\wordcloud_wechat\wechat_wc
|
||
npm ci
|
||
Copy-Item .env.example .env
|
||
npm run dev:weapp
|
||
```
|
||
|
||
最后一条命令保持运行。Taro 会持续把源码编译到 `dist/`；它不是服务器，也不需要在 Windows 安装后端 Node。
|
||
|
||
2. 打开微信开发者工具，选择 **导入项目**，目录选择 `G:\wordcloud_wechat\wechat_wc`。若提示 AppID，使用项目已有 AppID；仅查看 UI 也可选择测试号/游客模式（以工具实际选项为准）。
|
||
3. 等待终端首次构建完成，在开发者工具点顶部 **编译**。中间的 **模拟器** 就是小程序运行画面；切换底部或右侧的 **Console** 看前端异常、**Network** 看接口请求。以后保存 `src` 中的文件，Taro 会更新 `dist`，工具会自动或在点“编译”后刷新。
|
||
4. 为本机 HTTP 接口联调，打开开发者工具的 **详情 → 本地设置**，勾选“**不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书**”。仅本机开发使用，提交/真机预览前必须关闭。
|
||
|
||
前端 `.env` 已提供：
|
||
|
||
```dotenv
|
||
TARO_APP_API_BASE_URL=http://127.0.0.1:3090
|
||
```
|
||
|
||
它会在 `npm run dev:weapp` 编译时注入；`src/utils/request.ts` 因而请求本机 Docker 后端。更换 `.env` 后必须重启该 Taro 命令。Taro 环境变量与构建调试方式可参阅 [Taro 官方文档](https://docs.taro.zone/docs/env-mode-config) 和 [调试文档](https://docs.taro.zone/docs/envs-debug)。
|
||
|
||
## 联调检查顺序
|
||
|
||
```text
|
||
浏览器 /docs、/api/products 正常
|
||
↓
|
||
Taro 终端构建成功，dist/ 更新
|
||
↓
|
||
微信开发者工具导入 wechat_wc 并编译
|
||
↓
|
||
Network 中商品请求为 http://127.0.0.1:3090/api/products，状态 200
|
||
↓
|
||
商品页展示 R1 数据
|
||
```
|
||
|
||
注意：`127.0.0.1` 仅代表运行开发者工具的这台 Windows 电脑。它适合模拟器，不适合真实手机；真机或他人联调时，应改为可访问的 HTTPS 测试域名，并在微信公众平台配置合法 request 域名。生产环境通常让 Nginx/Caddy 作为 HTTPS 入口，应用、PostgreSQL、Redis 仍留在 Docker 内部网络，不对公网暴露。
|