feat: 汉字介绍待续

2026-02-09 13:30:43 +08:00
parent b13ab6f9fb
commit 3569961115
10 changed files with 36260 additions and 16 deletions
@@ -0,0 +1,201 @@
+# 使用 1Panel + OpenResty 部署 pipi-assets
+
+将 voice-production 的静态资源（voice、char、后续 image）通过 1Panel 安装的 OpenResty 对外提供，并绑定二级域名。OpenResty 与 Nginx 配置兼容，可直接使用本项目生成的配置。
+
+---
+
+## 一、前置条件
+
+- 服务器已安装 [1Panel](https://1panel.cn/)
+- 已通过 1Panel **应用商店** 安装 **OpenResty**
+- 项目代码在服务器上（如 `/home/joey/sites/platform-pipi`），或能在本机执行部署脚本并同步到服务器
+
+1Panel 默认安装目录为 `/opt/1panel`，下文中 OpenResty 相关路径均以此为准；若你的 1Panel 安装在其他目录，请替换为实际路径。
+
+---
+
+## 二、1Panel 中 OpenResty 的目录约定
+
+OpenResty 在 1Panel 中以容器方式运行，宿主机与容器路径对应关系如下：
+
+| 用途         | 宿主机路径（示例） | 容器内路径 |
+|--------------|--------------------|------------|
+| 站点配置片段 | `.../openresty/conf/conf.d/` | `/usr/local/openresty/nginx/conf/conf.d/` |
+| 网站根目录   | `.../openresty/www/`         | `/www`     |
+
+完整宿主机路径（1Panel 默认）：
+
+- 配置目录：`/opt/1panel/apps/openresty/openresty/conf/conf.d/`
+- 网站目录：`/opt/1panel/apps/openresty/openresty/www/`
+
+我们将把 pipi-assets 放在网站目录下，例如：`www/pipi-assets`，容器内访问为 `/www/pipi-assets`。
+
+---
+
+## 三、部署静态资源到 OpenResty 可访问的目录
+
+### 3.1 确定目标目录
+
+在**宿主机**上，使用 1Panel OpenResty 的网站目录下的子目录作为发布目录（请按你的 1Panel 安装路径调整）：
+
+```bash
+# 1Panel 默认安装目录为 /opt/1panel，若不同请修改
+OPENRESTY_WWW="/opt/1panel/apps/openresty/openresty/www"
+TARGET="${OPENRESTY_WWW}/pipi-assets"
+sudo mkdir -p "$TARGET"
+sudo chown -R $USER:$USER "$TARGET"
+```
+
+记下 `TARGET` 的取值（下文中称为「pipi-assets 宿主机路径」），后续部署脚本会用到。
+
+### 3.2 方式 A：在服务器上执行部署脚本（推荐）
+
+项目已在服务器上时（如 `/home/joey/sites/platform-pipi`）：
+
+```bash
+cd /home/joey/sites/platform-pipi/packages/voice-production
+pnpm install
+# 将 data/ 拷贝到 OpenResty 的 www/pipi-assets
+node scripts/deploy-assets.js --target /opt/1panel/apps/openresty/openresty/www/pipi-assets
+```
+
+请将 `--target` 改为你在 3.1 中使用的实际路径。
+
+### 3.3 方式 B：本机生成后同步到服务器
+
+在本机执行：
+
+```bash
+cd platform-pipi/packages/voice-production
+pnpm run deploy-assets:local
+rsync -avz --delete ./pipi-assets/ 用户@服务器IP:/opt/1panel/apps/openresty/openresty/www/pipi-assets/
+```
+
+若服务器上该目录需要 root，可先同步到用户目录，再 SSH 到服务器用 root 拷贝到上述路径。
+
+---
+
+## 四、添加 OpenResty 站点配置
+
+OpenResty 与 Nginx 配置兼容。有两种方式添加 pipi-assets 的 server 配置。
+
+### 4.1 方式一：在 1Panel 中创建网站（推荐）
+
+1. 登录 1Panel → **网站** → 点击 **创建网站**。
+2. 选择 **静态网站**（或仅需“运行目录”的站点类型）。
+3. 填写：
+   - **主域名**：你的二级域名（如 `assets.yourdomain.com`）。
+   - **运行目录**：容器内路径，填 **`/www/pipi-assets`**（对应宿主机 `.../www/pipi-assets`）。
+   - 若有「网站路径」「根目录」等，同样填 **`/www/pipi-assets`**。
+4. 创建完成后，在网站列表中找到该站点，进入 **配置** / **配置文件**，确认 `server` 块中：
+   - `root` 或 `alias` 指向 **`/www/pipi-assets`**；
+   - 若有 `location /`，可保持或按需增加下面「推荐 location」中的缓存与跨域头。
+
+若 1Panel 生成的默认配置已能正确访问 `/www/pipi-assets` 下的文件，可不必改；否则可把下面 4.2 的配置内容合并进去。
+
+### 4.2 方式二：手动添加 conf.d 配置片段
+
+在**宿主机**上创建新的配置文件（路径按 1Panel 实际安装目录调整）：
+
+```bash
+sudo nano /opt/1panel/apps/openresty/openresty/conf/conf.d/pipi-assets.conf
+```
+
+写入以下内容（将 `server_name` 改为你的二级域名）：
+
+```nginx
+# pipi-assets 静态资源（voice / char / image）
+server {
+    listen 80;
+    server_name assets.yourdomain.com;
+
+    root /www/pipi-assets;
+    autoindex off;
+
+    location /voice/ {
+        alias /www/pipi-assets/voice/;
+        add_header Cache-Control "public, max-age=86400";
+    }
+    location /char/ {
+        alias /www/pipi-assets/char/;
+        add_header Cache-Control "public, max-age=3600";
+        add_header Access-Control-Allow-Origin "*";
+    }
+    location /image/ {
+        alias /www/pipi-assets/image/;
+        add_header Cache-Control "public, max-age=86400";
+    }
+
+    location /health {
+        return 200 "ok";
+        add_header Content-Type text/plain;
+    }
+}
+```
+
+注意：这里所有路径均为**容器内路径**（`/www/pipi-assets`），因为 OpenResty 在容器中运行。
+
+---
+
+## 五、重载 OpenResty
+
+- **1Panel 界面**：网站 → OpenResty 工具栏 → 点击 **重载**，使新配置生效且不中断服务。
+- **命令行**（若你有权限进入容器或宿主机上能执行 1Panel 管理的 OpenResty）：
+  ```bash
+  # 仅当 1Panel 使用 systemd 管理 OpenResty 时可能可用，否则以 1Panel 重载为准
+  # openresty -s reload
+  ```
+建议以 1Panel 的 **重载** 为准。
+
+---
+
+## 六、DNS 与 HTTPS
+
+1. **DNS**：在域名服务商为二级域名（如 `assets.yourdomain.com`）添加 **A 记录**，指向当前服务器公网 IP。
+2. **HTTPS**：
+   - 1Panel 网站列表中，进入该站点 → **SSL** / **证书**，选择 1Panel 提供的 **Let's Encrypt** 或上传自有证书。
+   - 开启 HTTPS 后，OpenResty 会监听 443 并指向同一 `root`（/www/pipi-assets），无需改文档中的路径。
+
+---
+
+## 七、使用本项目生成的 Nginx 配置（可选）
+
+本项目 `deploy-assets.js` 生成的配置默认是给「系统 Nginx」用的，`root` 为宿主机路径。给 OpenResty 用时需把 `root` 改为容器内路径：
+
+- 生成配置时目标仍用宿主机路径（仅用于拷贝 data）：
+  ```bash
+  node scripts/deploy-assets.js --target /opt/1panel/apps/openresty/openresty/www/pipi-assets
+  ```
+- 打开生成的 `scripts/nginx-pipi-assets.conf`，将其中**所有** `root` / `alias` 的路径从「宿主机路径」改为 **`/www/pipi-assets`**（或 `/www/pipi-assets/voice/` 等），再复制到 `conf.d/pipi-assets.conf` 使用。
+
+---
+
+## 八、验证
+
+- 健康检查：`http://你的二级域名/health` 或 `https://...` → 应返回 `ok`。
+- 角色 JSON：`http://你的二级域名/char/char_introduce.json` → 应返回 JSON。
+- 语音：`http://你的二级域名/voice/xxx.mp3` → 可播放或下载。
+
+---
+
+## 九、后续更新资源
+
+- **方式 A**：在服务器项目目录执行  
+  `node scripts/deploy-assets.js --target /opt/1panel/apps/openresty/openresty/www/pipi-assets`  
+  覆盖更新 `pipi-assets` 目录内容。
+- **方式 B**：本机执行 `pnpm run deploy-assets:local` 后，用 rsync 同步到服务器上述 `pipi-assets` 路径。
+
+更新后无需重启 OpenResty，直接刷新页面即可。
+
+---
+
+## 十、路径与注意事项小结
+
+| 项目           | 说明 |
+|----------------|------|
+| 1Panel 安装目录 | 常见为 `/opt/1panel`，以实际为准。 |
+| 宿主机 pipi-assets | `.../openresty/openresty/www/pipi-assets`，部署脚本和 rsync 写这里。 |
+| 容器内 root     | 配置里统一用 **`/www/pipi-assets`**。 |
+| 重载            | 在 1Panel 网站页对 OpenResty 使用 **重载**，不要直接改容器内文件。 |
+
+若你使用非默认 1Panel 安装路径，将文中 `/opt/1panel` 全部替换为你的安装目录即可。
@@ -0,0 +1,190 @@
+# voice-production 部署到 Ubuntu 云服务器
+
+将 `voice-production` 的静态资源（voice、char、后续图片）部署到 Ubuntu，用 Nginx 提供访问并绑定二级域名。
+
+---
+
+## 一、服务器准备
+
+### 1. 安装 Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx -y
+sudo systemctl enable nginx
+sudo systemctl start nginx
+```
+
+### 2. 安装 Node.js 与 pnpm（用于在服务器上执行部署脚本）
+
+若你打算在服务器上跑 `deploy-assets` 和后续的生成脚本，需要 Node：
+
+```bash
+# Node 20 LTS（推荐）
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# pnpm
+sudo npm install -g pnpm
+```
+
+若你只打算从本机把已生成好的 `pipi-assets` 同步到服务器，可跳过 pnpm，但至少保留 Node 以便将来在服务器上跑脚本。
+
+### 3. 创建资源目录（若用脚本部署会自动创建，也可先建）
+
+```bash
+sudo mkdir -p /var/www/pipi-assets
+sudo chown $USER:$USER /var/www/pipi-assets
+```
+
+---
+
+## 二、部署方式（二选一）
+
+### 方式 A：在服务器上拉代码并执行部署脚本（推荐）
+
+适合：代码已在 Git 仓库，服务器能访问仓库。
+
+**1. 在服务器上克隆/拉取项目**
+
+```bash
+# 进入你放项目的目录，例如
+cd /var/www
+sudo git clone <你的仓库地址> pipi-learn
+cd pipi-learn/platform-pipi/packages/voice-production
+# 若已存在目录则只拉取
+# git pull
+```
+
+**2. 安装依赖并执行部署**
+
+```bash
+pnpm install
+pnpm run deploy-assets:server
+```
+
+会把 `data/` 下内容拷贝到 `/var/www/pipi-assets/`，并在当前目录生成 `scripts/nginx-pipi-assets.conf`。
+
+**3. 把 Nginx 配置放到系统目录并启用**
+
+```bash
+# 若需改二级域名，先编辑 scripts/nginx-pipi-assets.conf 里的 server_name
+sudo cp scripts/nginx-pipi-assets.conf /etc/nginx/sites-available/pipi-assets
+sudo ln -sf /etc/nginx/sites-available/pipi-assets /etc/nginx/sites-enabled
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+**4. 配置 DNS**
+
+在域名服务商处为二级域名（如 `assets.yourdomain.com`）添加 **A 记录**，指向该云服务器的公网 IP。
+
+**5.（可选）HTTPS**
+
+```bash
+sudo apt install certbot python3-certbot-nginx -y
+sudo certbot --nginx -d assets.yourdomain.com
+```
+
+按提示选择即可，证书会自动写入 Nginx 配置。
+
+---
+
+### 方式 B：本机生成后同步到服务器
+
+适合：在本地生成 voice/char，只把静态文件上传到服务器。
+
+**1. 本机生成并拷贝到“服务器目标结构”**
+
+在 Mac 上：
+
+```bash
+cd platform-pipi/packages/voice-production
+pnpm run deploy-assets:local   # 生成 pipi-assets/
+```
+
+**2. 把 pipi-assets 同步到服务器**
+
+```bash
+rsync -avz --delete ./pipi-assets/ 用户名@服务器IP:/var/www/pipi-assets/
+```
+
+若服务器上 `/var/www/pipi-assets` 需要 sudo，可先同步到用户目录再在服务器上移动：
+
+```bash
+rsync -avz --delete ./pipi-assets/ 用户名@服务器IP:~/pipi-assets/
+# 登录服务器后
+ssh 用户名@服务器IP
+sudo rm -rf /var/www/pipi-assets/* && sudo cp -r ~/pipi-assets/* /var/www/pipi-assets/
+```
+
+**3. 在服务器上准备 Nginx 配置**
+
+- 要么在服务器上拉取一遍 voice-production 代码，执行一次 `pnpm run deploy-assets:server`，只为了生成 `scripts/nginx-pipi-assets.conf`，再按方式 A 第 3 步拷贝并启用；
+- 要么在本机生成配置后上传。本机执行：
+
+```bash
+node scripts/deploy-assets.js --target /var/www/pipi-assets --nginx ./scripts/nginx-pipi-assets.conf
+```
+
+把生成的 `scripts/nginx-pipi-assets.conf` 用 scp 传到服务器，再在服务器上：
+
+```bash
+sudo cp nginx-pipi-assets.conf /etc/nginx/sites-available/pipi-assets
+sudo ln -sf /etc/nginx/sites-available/pipi-assets /etc/nginx/sites-enabled
+```
+
+**4. 修改配置里的 server_name（若尚未改）**
+
+```bash
+sudo nano /etc/nginx/sites-available/pipi-assets
+# 将 server_name assets.yourdomain.com; 改为你的二级域名
+```
+
+**5. 测试并重载 Nginx**
+
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+DNS 与 HTTPS 步骤同方式 A 的 4、5。
+
+---
+
+## 三、修改二级域名
+
+生成的 `nginx-pipi-assets.conf` 里默认是 `server_name assets.yourdomain.com;`。
+
+- **方式 A**：在服务器上编辑 `scripts/nginx-pipi-assets.conf` 再拷贝到 `/etc/nginx/sites-available/`，或直接编辑 `/etc/nginx/sites-available/pipi-assets`。
+- **方式 B**：本机生成配置后编辑再上传，或在服务器上编辑 `/etc/nginx/sites-available/pipi-assets`。
+
+改完后执行：
+
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+---
+
+## 四、后续更新资源
+
+- **方式 A**：在服务器上进入 `voice-production` 目录，执行 `git pull`，再执行 `pnpm run deploy-assets:server`；若在服务器上跑生成脚本，先 `pnpm run generate-voice` 等再执行 `deploy-assets:server`。
+- **方式 B**：本机重新生成/拷贝后，再执行一次 `rsync` 同步到服务器。
+
+---
+
+## 五、常用命令速查
+
+| 说明            | 命令                                     |
+| --------------- | ---------------------------------------- |
+| 测试 Nginx 配置 | `sudo nginx -t`                          |
+| 重载 Nginx      | `sudo systemctl reload nginx`            |
+| 查看 Nginx 状态 | `sudo systemctl status nginx`            |
+| 查看站点日志    | `sudo tail -f /var/log/nginx/access.log` |
+
+---
+
+## 六、验证
+
+- 健康检查：`https://你的二级域名/health` 应返回 `ok`。
+- 角色 JSON：`https://你的二级域名/char/char_introduce.json` 应返回 JSON。
+- 语音：`https://你的二级域名/voice/xxx.mp3` 应能播放或下载。