jack/digital-psychology
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 补充 Ubuntu+MySQL 并存与 PostgreSQL 部署指南

Browse Source 
DEPLOY-MINI-PROGRAM-H5 增加 PG 安装三种方式、Go API systemd、Checklist 与双库架构说明。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
jackyu66git
2026-08-25 00:46:58 +08:00
co-authored by Cursor
parent 8d856fb56c
commit ebc2d3ad80
1 changed files with 250 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOY-MINI-PROGRAM-H5.md
+250 -40
View File
@@ -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