platform-pipi/packages/voice-production/docs/1Panel-OpenResty部署pipi-assets.md

# 使用 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` 全部替换为你的安装目录即可。