# 小程序联调：把后端部署到你的服务器

> 目标：让小程序能连上 `server/index.js`。
> 你现在看到「**未连接**」，是因为小程序指向的是**下载站**（纯静态，没有 API）。

---

## 一、先说清楚：为什么下载站不行

```
小程序  ──→  https://a58375f42ae0370ad.app.workbuddy.host/api/copy
                    ↓
                 404 Not Found
```

那个域名只托管静态文件（HTML + zip 分片），**永远不会返回 API 数据**。
它是给人**下载安装包**用的，不是给小程序当后端用的。

**API 必须由 `server/index.js` 提供**，而它得跑在一台**长期在线**的服务器上。

---

## 二、服务器准备

| 项 | 要求 |
|---|---|
| 系统 | 任意 Linux（宝塔 / 纯净都行） |
| **Node.js** | **≥ 18**（`engines` 里写死的） |
| **FFmpeg** | 必须装（合成视频用），要带 `libopenh264` 编码 |
| 中文字体 | 建议装 Noto Sans CJK（否则合成视频里的中文会变方块） |
| 端口 | 默认 **3000**，可改 |

---

## 三、部署（四步）

### 第 1 步：把代码传上去

```bash
# 方式 A：git
git clone <你的仓库> /www/wwwroot/avc && cd /www/wwwroot/avc

# 方式 B：从下载站下全量包，解压
unzip avc-upgrade-20261013-v43.zip -d /www/wwwroot/avc && cd /www/wwwroot/avc
```

### 第 2 步：跑部署脚本

项目里已经带了脚本，它会自动检查环境、装依赖、用 PM2 拉起服务：

```bash
cd /www/wwwroot/avc

# 先看看环境缺什么（只检查，不改动）
bash scripts/deploy.sh --check

# 正式部署（把域名换成你自己的）
bash scripts/deploy.sh --domain https://你的域名 --pm2
```

> 脚本做的事：检查 Node/FFmpeg/字体 → `npm install` → PM2 启动并设置开机自启。
> **它不碰数据库和 OSS 配置** —— 那些交给下一步的安装向导。

### 第 3 步：走安装向导

浏览器打开 `https://你的域名`，会自动跳到安装向导：

- 选**存储驱动**（本地磁盘 / MySQL / OSS，看你需求）
- 填**管理员账号密码**
- 系统自动建表、生成密钥

> 也可以跳过向导，手工写 `.env`（见下面第五节）。

### 第 4 步：配微信凭据

小程序登录**必须**配这个，否则 `/api/auth/wx-login` 会直接返回 **503**：

```ini
WX_APPID=wx你的AppID
WX_SECRET=你的AppSecret
```

两种填法：
- **后台界面**：「系统设置」→ 小程序配置区（加密存库，只显示「是否已配置」）
- **`.env` 文件**：加上面两行，然后 `pm2 restart` 重启

---

## 四、让小程序连上（关键一步）

后端跑起来后，有两个地方要改：

### 1️⃣ 注入服务端地址到小程序

```bash
cd /www/wwwroot/avc
npm run inject:api -- https://你的域名
```

这会把地址写进 `miniprogram/_config.js`。验证一下：

```bash
npm run inject:api -- --show
```

### 2️⃣ 配置微信后台的服务器域名（**最容易漏**）

到 <https://mp.weixin.qq.com> → **开发管理 → 开发设置 → 服务器域名**，把域名加进：

| 类型 | 填什么 |
|---|---|
| **request 合法域名** | `https://你的域名` |
| **downloadFile 合法域名** | `https://你的域名` |

> ⚠️ **必须是 HTTPS**，且域名**已备案**。小程序正式版不接受 HTTP 与 IP 地址。
> 没配这个，真机上所有请求都会被拦（模拟器可以靠「不校验合法域名」绕过，真机不行）。

### 3️⃣ 重新导入小程序

改了 `_config.js` 后，回开发者工具**重新编译**（或重新导入）即可。

---

## 五、有用的命令

```bash
# 看服务状态
pm2 status
pm2 logs avc --lines 50

# 重启（改了 .env 之后必须重启）
pm2 restart avc

# 环境检查
bash scripts/deploy.sh --check

# 备份
bash scripts/backup.sh

# 看小程序当前注入的地址
npm run inject:api -- --show

# 清空注入（回退到 config.js 的兜底地址）
npm run inject:api -- --clear
```

---

## 六、验证通了没

### 服务器上自测

```bash
curl http://127.0.0.1:3000/api/health
# 期望：{"ok":true,"status":"up","version":"1.1.26",...}

curl https://你的域名/api/copy
# 期望：返回 JSON 数组，不是 404
```

### 小程序里自测

打开开发者工具 → **调试器 Console**，应该看到：

```
[avc] apiBase = https://你的域名
```

再用微信开发者工具自带的 **「Network」面板**看 `/api/copy` 是否 200。

---

## 七、环境变量速查

按需在 `.env` 里配（**不是所有都要**）：

```ini
# ---- 基础 ----
PORT=3000
HOST=0.0.0.0
PUBLIC_ORIGIN=https://你的域名

# ---- 管理员账号（不配则每次重启生成临时口令）----
ADMIN_USER=admin
ADMIN_PASS=你的强密码

# ---- 鉴权密钥（不配则自动生成并存 data/secret.key）----
APP_SECRET=一串随机字符串

# ---- 数据库（用 MySQL 时配）----
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=xxx
DB_PASSWORD=xxx
DB_NAME=avc

# ---- 存储驱动 ----
STORAGE_DRIVER=local          # local | mysql | oss | cloudbase
MEDIA_DRIVER=local

# ---- 微信小程序（**联调必配**）----
WX_APPID=wx...
WX_SECRET=...
```

> 完整的可配项见 `server/lib/cloud-config.js`。**没配的项会走默认值**，
> 启动日志会逐条打印当前生效的配置，照着看就行。

---

## 八、排错对照表

| 现象 | 原因 | 解决 |
|---|---|---|
| 小程序「未连接」 | apiBase 指向静态站 | 跑 `npm run inject:api` |
| Console 报 `url not in domain list` | 微信后台没配合法域名 | 第四节第 2 步 |
| 登录返回 **503** | 没配 WX_APPID / WX_SECRET | 第三节第 4 步 |
| 请求 404 | 后端没启动 / 域名指向了别的服务 | `curl .../api/health` 自测 |
| 真机连不上、模拟器正常 | 用了 HTTP 或 IP | 换成已备案的 HTTPS 域名 |
| 合成视频中文变方块 | 缺中文字体 | 装 Noto Sans CJK，重启 |
| 重启后管理员令牌失效 | 没配 `APP_SECRET` | 写上固定值 |

---

## 九、一句话总结

```
1. 服务器装 Node 18+ / FFmpeg        →  bash scripts/deploy.sh --check
2. 部署并起服务                       →  bash scripts/deploy.sh --domain ... --pm2
3. 走安装向导配数据库/账号
4. 配 WX_APPID / WX_SECRET            ← 小程序登录必需
5. npm run inject:api -- https://你的域名
6. 微信后台加 request / downloadFile 合法域名
7. 开发者工具重新编译
```

**第 4 步和第 6 步是最容易漏的两处。**