From ebc2d3ad802040f8249df408cd7e278dd0f89cf1 Mon Sep 17 00:00:00 2001 From: jackyu66git Date: Tue, 25 Aug 2026 00:46:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20Ubuntu+MySQL=20?= =?UTF-8?q?=E5=B9=B6=E5=AD=98=E4=B8=8E=20PostgreSQL=20=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DEPLOY-MINI-PROGRAM-H5 增加 PG 安装三种方式、Go API systemd、Checklist 与双库架构说明。 Co-authored-by: Cursor --- docs/DEPLOY-MINI-PROGRAM-H5.md | 290 ++++++++++++++++++++++++++++----- 1 file changed, 250 insertions(+), 40 deletions(-) diff --git a/docs/DEPLOY-MINI-PROGRAM-H5.md b/docs/DEPLOY-MINI-PROGRAM-H5.md index 238080c..538f47e 100644 --- a/docs/DEPLOY-MINI-PROGRAM-H5.md +++ b/docs/DEPLOY-MINI-PROGRAM-H5.md @@ -50,67 +50,223 @@ export const YXG_H5_HOME_URL = `${YXG_H5_BASE}?mp=1` | downloadFile 合法域名 | `https://miniapp.yuxingu.com.cn`（维持现状） | | socket 合法域名 | 无需配置 | -### 2.3 服务器 +### 2.3 服务器（Ubuntu 典型） -- 一台可跑 Nginx + Go 二进制（或容器）的 VPS -- PostgreSQL（Go API 用；可与现有库同机或托管） -- Java 微服务 + `miniapp.yuxingu.com.cn` 保持现有部署，本说明不覆盖 +| 软件 | 用途 | 端口 | +|------|------|------| +| **MySQL** | Java 旧后台（`miniapp.yuxingu.com.cn`） | 3306 | +| **PostgreSQL** | Go API 愈心魔方（**必须另装，不能复用 MySQL**） | 5432 | +| **Nginx** | HTTPS、`h5.yuxingu.com.cn` 静态 + 反代 | 443 | +| **Go 二进制** | `yuxingu-api`，建议仅监听 `127.0.0.1:8080` | 8080 | + +Java 微服务 + `miniapp.yuxingu.com.cn` 保持现有部署，本说明不覆盖 Java/MySQL 的运维。 + +### 2.4 双数据库说明（Ubuntu 上已是 MySQL） + +**愈心谷 Go API 只支持 PostgreSQL**（pgx + `apps/api/migrations/` 内 PG 语法）。 +**不能**把 `config.local.yaml` 指到 MySQL，也**不要**把 Java 的 MySQL 表直接给 Go 用。 + +| 业务 | 后端 | 数据库 | +|------|------|--------| +| 小程序：咨询 / 测评 / 订单 / 登录 | Java（rp-server-psychic） | **MySQL**（已有） | +| 愈心魔方 H5：档案 / 问答 / 报告等 | Go（digital-psychology） | **PostgreSQL**（新增） | + +推荐：**同一台 Ubuntu 上 MySQL 与 PostgreSQL 并存**（端口不同，互不影响）。 + +``` +Ubuntu VPS +├── MySQL :3306 → miniapp.yuxingu.com.cn（不动） +├── PostgreSQL :5432 → 愈心魔方 Go API（新增） +├── yuxingu-api :8080 → 127.0.0.1（Nginx 反代） +└── Nginx :443 + ├── h5.yuxingu.com.cn/psy/ → user-h5 静态 + └── h5.yuxingu.com.cn/psy/api/ → Go API +``` --- -## 3. Go API 部署 +## 3. PostgreSQL 部署（Ubuntu） + +Go API 启动前必须先有可用的 PostgreSQL 实例。 + +### 3.1 方式 A：系统包安装（推荐，与 MySQL 并存） + +```bash +# Ubuntu 22.04 / 24.04 +sudo apt update +sudo apt install -y postgresql postgresql-contrib +sudo systemctl enable postgresql +sudo systemctl start postgresql + +# 确认端口（默认 5432，与 MySQL 3306 不冲突） +ss -tlnp | grep 5432 +``` + +创建专用库与用户（**请替换强密码**）： + +```bash +sudo -u postgres psql <<'SQL' +CREATE USER yuxingu WITH PASSWORD '替换为强密码'; +CREATE DATABASE yuxingu OWNER yuxingu; +GRANT ALL PRIVILEGES ON DATABASE yuxingu TO yuxingu; +SQL +``` + +仅本机访问（默认已是）时可加固： + +```bash +# 可选：确认 listen 仅 localhost（/etc/postgresql/*/main/postgresql.conf） +# listen_addresses = 'localhost' +sudo systemctl reload postgresql +``` + +连通性自测： + +```bash +psql "postgresql://yuxingu:替换为强密码@127.0.0.1:5432/yuxingu?sslmode=disable" -c 'SELECT 1' +``` + +### 3.2 方式 B：Docker 只跑 Postgres（系统 MySQL 不动） + +已安装 Docker 时，可不必 `apt install postgresql`： + +```bash +docker run -d --name yuxingu-pg \ + --restart unless-stopped \ + -e POSTGRES_USER=yuxingu \ + -e POSTGRES_PASSWORD='替换为强密码' \ + -e POSTGRES_DB=yuxingu \ + -p 127.0.0.1:5432:5432 \ + -v yuxingu-pg-data:/var/lib/postgresql/data \ + postgres:16-alpine +``` + +`config.local.yaml` 中 `database.host` 仍为 `127.0.0.1`，`port: 5432`。 + +### 3.3 方式 C：云托管 PostgreSQL + +使用 RDS / 云数据库 PostgreSQL 时，将 `config.local.yaml` 的 `database.host` 改为云内网地址，并按云厂商要求设置 `sslmode`（常为 `require`）。 +安全组需允许 **应用服务器** 访问 5432，**不要**对公网开放 PostgreSQL。 + +### 3.4 迁移说明 + +- 表结构由 Go API **启动时自动迁移**（`apps/api/migrations/`），无需手工导入 SQL。 +- 首次 `./yuxingu-api` 或 `systemctl start yuxingu-api` 成功后，库内应有 `migrations` 相关表及业务表。 +- **禁止**把 Java MySQL 的 `psychic_*` 表导入 PostgreSQL 替代迁移。 + +--- + +## 4. Go API 部署 仓库：`digital-psychology` -### 3.1 构建 +### 4.1 服务器目录建议 ```bash -cd /path/to/digital-psychology/apps/api +sudo mkdir -p /opt/yuxingu +sudo chown "$USER:$USER" /opt/yuxingu + +# 拉代码（示例） +cd /opt/yuxingu +git clone https://git.jackyu66.com/jack/digital-psychology.git +cd digital-psychology/apps/api +``` + +也可在本机构建 `yuxingu-api` 二进制 + scp 到服务器，仅同步 `apps/api/` 与 `config.local.yaml`。 + +### 4.2 构建 + +```bash +cd /opt/yuxingu/digital-psychology/apps/api go test ./... go build -o yuxingu-api ./cmd/server ``` -### 3.2 配置 +服务器若无 Go toolchain，在开发机交叉编译后上传： ```bash +# 开发机（Linux amd64 示例） +GOOS=linux GOARCH=amd64 go build -o yuxingu-api ./cmd/server +scp yuxingu-api user@server:/opt/yuxingu/digital-psychology/apps/api/ +``` + +### 4.3 配置（生产） + +```bash +cd /opt/yuxingu/digital-psychology/apps/api cp config.example.yaml config.local.yaml -# 编辑 config.local.yaml：database、deepseek.api_key（Ask 需要）等 +chmod 600 config.local.yaml ``` -生产环境建议用环境变量覆盖敏感项，勿把密钥提交 Git。 +`config.local.yaml` 示例（**PostgreSQL，非 MySQL**）： -### 3.3 数据库迁移 +```yaml +app: + env: prod + http_addr: "127.0.0.1:8080" # 仅本机，由 Nginx 反代对外 -API 启动时会自动应用 `apps/api/migrations/`。首次部署前确保 PostgreSQL 已创建库和用户。 +database: + host: 127.0.0.1 + port: 5432 + user: yuxingu + password: "替换为强密码" + name: yuxingu + sslmode: disable + +deepseek: + api_key: "" # Ask 真实回复需要；展示可先留空 + base_url: "https://api.deepseek.com" + model: "deepseek-chat" + timeout_sec: 60 + +admin: + bootstrap_username: admin + bootstrap_password: "替换为强密码" +``` + +生产环境建议用环境变量 / 密钥管理覆盖敏感项，勿把 `config.local.yaml` 提交 Git。 + +### 4.4 首次启动与迁移 ```bash -# 本地仅 DB 示例 -cd /path/to/digital-psychology -docker compose -f docker-compose.dev.yml up -d +cd /opt/yuxingu/digital-psychology/apps/api +./yuxingu-api +# 看到监听 127.0.0.1:8080、迁移无报错即可 Ctrl+C，改 systemd 常驻 ``` -### 3.4 运行（示例 systemd） +### 4.5 systemd 常驻 ```ini # /etc/systemd/system/yuxingu-api.service [Unit] -Description=Yuxingu Go API -After=network.target +Description=Yuxingu Go API (愈心魔方) +After=network.target postgresql.service +Wants=postgresql.service [Service] Type=simple -WorkingDirectory=/opt/yuxingu/apps/api -ExecStart=/opt/yuxingu/apps/api/yuxingu-api +User=www-data +Group=www-data +WorkingDirectory=/opt/yuxingu/digital-psychology/apps/api +ExecStart=/opt/yuxingu/digital-psychology/apps/api/yuxingu-api Environment=APP_ENV=prod Restart=on-failure +RestartSec=5 [Install] WantedBy=multi-user.target ``` -API 默认监听 `:8080`（见 `config.local.yaml` 的 `http_addr`）。 +若 PostgreSQL 用 Docker 容器名 `yuxingu-pg`，将 `After=` 改为 `docker.service` 或去掉 PostgreSQL 依赖。 -### 3.5 健康检查 +```bash +sudo systemctl daemon-reload +sudo systemctl enable yuxingu-api +sudo systemctl start yuxingu-api +sudo systemctl status yuxingu-api +``` + +### 4.6 健康检查 ```bash curl -sS http://127.0.0.1:8080/api/v1/healthz @@ -119,9 +275,9 @@ curl -sS http://127.0.0.1:8080/api/v1/healthz --- -## 4. H5 构建与 Nginx 部署 +## 5. H5 构建与 Nginx 部署 -### 4.1 构建静态资源 +### 5.1 构建静态资源 ```bash cd /path/to/digital-psychology @@ -132,7 +288,7 @@ npm run build:h5 构建产物 `base` 为 `/psy/`，与线上路径一致，**无需改 `baseURL`**（客户端请求 `/psy/api/v1/...`）。 -### 4.2 上传到服务器 +### 5.2 上传到服务器 ```bash rsync -avz --delete apps/user-h5/dist/ user@your-server:/var/www/yuxingu-h5/psy/ @@ -147,7 +303,7 @@ rsync -avz --delete apps/user-h5/dist/ user@your-server:/var/www/yuxingu-h5/psy/ └── ... ``` -### 4.3 Nginx 配置（推荐：H5 + API 同域） +### 5.3 Nginx 配置（推荐：H5 + API 同域） ```nginx server { @@ -194,7 +350,7 @@ reload： sudo nginx -t && sudo systemctl reload nginx ``` -### 4.4 H5 embed 模式说明 +### 5.4 H5 embed 模式说明 小程序 WebView 打开 `https://h5.yuxingu.com.cn/psy/?mp=1` 时： @@ -204,13 +360,43 @@ sudo nginx -t && sudo systemctl reload nginx 浏览器直访 `https://h5.yuxingu.com.cn/psy/`（无 `mp=1`）仍为完整 H5 体验（含 TabBar）。 +### 5.5 ICP 备案页脚 + +`user-h5` / `admin-h5` 构建产物已含底部链接：**蜀ICP备2025140386号-2** → `https://beian.miit.gov.cn/`。 +部署 H5 后访问 `https://h5.yuxingu.com.cn/psy/` 应能在页面底部看到备案号。 + --- -## 5. 微信小程序部署 +## 6. 运营后台 admin-h5（可选） + +若需部署内部 Ops 后台（与愈心魔方同 Go API）： + +```bash +cd /path/to/digital-psychology +npm ci +npm run build:admin +# 产物：apps/admin-h5/dist/ +``` + +Nginx 可增加 location（与 H5 同机示例）： + +```nginx +location /psy/admin/ { + alias /var/www/yuxingu-admin/dist/; + try_files $uri $uri/ /psy/admin/index.html; +} +``` + +admin 前端请求走 `/psy/api/` 或 `/api/` 反代（与 `apps/admin-h5` 构建 `base` 一致）。 +登录使用 `config.local.yaml` 中 `admin.bootstrap_*` 初始账号。 + +--- + +## 7. 微信小程序部署 仓库：`yuxingu-Miniprogram-dev` -### 5.1 开发工具构建 +### 7.1 开发工具构建 1. 用 **HBuilderX** 打开 `yuxingu-Miniprogram-dev` 2. 菜单：**发行 → 小程序-微信** @@ -224,19 +410,19 @@ npx uni build -p mp-weixin 编译产物目录：`unpackage/dist/build/mp-weixin/`（或 dev 目录） -### 5.2 微信开发者工具 +### 7.2 微信开发者工具 1. 导入上述 `mp-weixin` 目录 2. AppID：`wx6782dd88e655f1a7`（见 `manifest.json`） 3. 预览 / 真机调试 -### 5.3 上传体验版 / 正式版 +### 7.3 上传体验版 / 正式版 1. 开发者工具 → **上传** 2. 登录 [微信公众平台](https://mp.weixin.qq.com/) → **管理 → 版本管理** 3. 将上传版本设为 **体验版** 供内部验收，或提交审核后发布 -### 5.4 发布前检查（小程序侧） +### 7.4 发布前检查（小程序侧） - [ ] `util/yxgConfig.js` 中 H5 地址为生产域名 - [ ] `util/requestConfig.js` 中 Java API 仍为 `https://miniapp.yuxingu.com.cn` @@ -245,9 +431,28 @@ npx uni build -p mp-weixin --- -## 6. 上线验证清单 +## 8. Ubuntu 一键部署顺序（Checklist） -### 6.1 服务端 +按顺序执行，避免愈心魔方 Tab 白屏： + +```text +□ 1. MySQL + Java（miniapp）已运行 — 无需本说明改动 +□ 2. 安装 PostgreSQL（§3.1 或 §3.2），建库 yuxingu +□ 3. 拉取 digital-psychology，构建 yuxingu-api（§4） +□ 4. 编写 config.local.yaml（database 指向 PostgreSQL:5432） +□ 5. systemctl start yuxingu-api，curl healthz 通 +□ 6. 本机 npm run build:h5，rsync 到 /var/www/yuxingu-h5/psy/ +□ 7. 配置 Nginx（§5.3），reload，curl https://h5.../psy/api/v1/healthz +□ 8. 浏览器打开 https://h5.yuxingu.com.cn/psy/?mp=1，确认备案号与页面 +□ 9. HBuilderX 发行小程序，上传体验版 +□ 10. 真机：愈心魔方 Tab + 咨询/测评 Tab 均正常 +``` + +--- + +## 9. 上线验证清单 + +### 9.1 服务端 ```bash # H5 首页 @@ -260,7 +465,7 @@ curl -sS https://h5.yuxingu.com.cn/psy/api/v1/healthz curl -I 'https://h5.yuxingu.com.cn/psy/?mp=1' ``` -### 6.2 微信开发者工具 / 真机 +### 9.2 微信开发者工具 / 真机 | 步骤 | 预期 | |------|------| @@ -271,20 +476,22 @@ curl -I 'https://h5.yuxingu.com.cn/psy/?mp=1' | 咨询 / 测评 Tab | 仍走 miniapp 旧接口，登录与订单正常 | | 未登录访问需登录能力 | 弹出微信手机号登录 | -### 6.3 常见故障 +### 9.3 常见故障 | 现象 | 原因 | 处理 | |------|------|------| | WebView 白屏 | 业务域名未配或校验文件缺失 | 微信后台 → 业务域名 → 重新校验 | | H5 内接口失败 | request 合法域名缺 `h5.yuxingu.com.cn` | 补充合法域名，等 5 分钟生效 | | 404 on `/psy/ask` 刷新 | Nginx 未配 SPA fallback | 确认 `try_files` 指向 `/psy/index.html` | -| API 502 | Go 未启动或反代路径错误 | 查 `yuxingu-api` 日志与 `proxy_pass` | +| API 502 | Go 未启动或反代路径错误 | 查 `journalctl -u yuxingu-api` 与 Nginx `proxy_pass` | +| API 连库失败 | 误配 MySQL 或 PG 密码/端口错 | `database` 必须 PostgreSQL；`psql` 自测 | | H5 仍显示底栏 | 未带 `mp=1` | 检查 `yxgConfig.js` 与 WebView URL | | 双层底栏 | H5 未进 embed 模式 | 确认 URL 含 `?mp=1` 且已部署最新 H5 | +| 迁移失败 | PG 权限不足 | `GRANT ALL ON DATABASE yuxingu TO yuxingu` | --- -## 7. 更新与回滚 +## 10. 更新与回滚 ### 仅更新愈心魔方（H5 + API） @@ -312,7 +519,7 @@ sudo systemctl restart yuxingu-api --- -## 8. 仓库与路径速查 +## 11. 仓库与路径速查 | 内容 | 路径 | |------|------| @@ -323,9 +530,12 @@ sudo systemctl restart yuxingu-api | H5 构建命令 | `digital-psychology` 根目录 `npm run build:h5` | | 本地开发 | Go：`cd apps/api && go run ./cmd/server`；H5：`npm run dev:h5` | +| ICP 常量 | `packages/utils/src/icp.ts` | +| 部署本文 | `docs/DEPLOY-MINI-PROGRAM-H5.md` | + --- -## 9. 后续（非展示期） +## 12. 后续（非展示期） - 微信登录与 Go Auth 统一（单账号） - Java 顾问/测评域逐步迁入 Go API