dekun
182 lines
5.3 KiB
Markdown
182 lines
5.3 KiB
Markdown
# LLM 中转网关 · PM2 部署说明
|
||
|
||
本文说明如何在服务器上使用 **PM2** 守护 **FastAPI（uvicorn）** 进程，实现崩溃自动拉起、开机自启与日志管理。
|
||
|
||
---
|
||
|
||
## 1. 前置条件
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| **Python** | 建议 3.10+，已加入 `PATH` |
|
||
| **Node.js** | 用于安装 PM2（LTS 即可） |
|
||
| **PM2** | `npm i -g pm2` |
|
||
| **本项目** | 含 `main.py`、`requirements.txt`，可选 `ecosystem.config.cjs` |
|
||
|
||
上游本地大模型（默认 `http://127.0.0.1:10434`）需在同一台机器或内网可达；若在大模型同一主机部署网关，确保端口未被占用（下文示例为 **8000**）。
|
||
|
||
---
|
||
|
||
## 2. 准备运行环境
|
||
|
||
在 **项目根目录**（与 `main.py` 同级）执行：
|
||
|
||
### Linux / macOS
|
||
|
||
```bash
|
||
cd /path/to/中转网关
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt -U
|
||
```
|
||
|
||
### Windows（PowerShell）
|
||
|
||
```powershell
|
||
cd C:\path\to\中转网关
|
||
python -m venv venv
|
||
.\venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt -U
|
||
```
|
||
|
||
在项目目录创建 **`gateway.json`**（可复制 `gateway.json.example`），填写 **`username`**、**`password`**；**`api_key`** 可留空，首次启动会自动写入 `sk-...`。也可用环境变量 **`GATEWAY_CONFIG`** 指定配置文件绝对路径。
|
||
|
||
确认可手动启动：
|
||
|
||
```bash
|
||
python -m uvicorn main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
浏览器访问 `http://服务器IP:8000` 正常后再交给 PM2。
|
||
|
||
---
|
||
|
||
## 3. 环境变量（生产必改）
|
||
|
||
| 变量 | 含义 | 建议 |
|
||
|------|------|------|
|
||
| `JWT_SECRET` | 签发网页登录 JWT 的密钥 | 长随机字符串，勿泄露 |
|
||
| `UPSTREAM_URL` | 上游 OpenAI 兼容服务根地址（无末尾 `/`） | 默认 `http://127.0.0.1:10434`，按实际修改 |
|
||
|
||
可在 shell 中导出，或在 PM2 的 `env` / `ecosystem.config.cjs` 中配置（见下文）。
|
||
|
||
---
|
||
|
||
## 4. 使用 PM2 启动（推荐 ecosystem）
|
||
|
||
项目根目录已提供 **`ecosystem.config.cjs`**：自动根据 **Windows / 非 Windows** 选择虚拟环境中的 Python 解释器，并启动：
|
||
|
||
`python -m uvicorn main:app --host 0.0.0.0 --port 8000`
|
||
|
||
### 4.1 修改配置
|
||
|
||
1. 用编辑器打开 `ecosystem.config.cjs`。
|
||
2. 在 `env` 里填写 **`JWT_SECRET`**（必填），按需修改 **`UPSTREAM_URL`**。
|
||
3. 若端口冲突，可在 `args` 中把 `8000` 改成其它端口。
|
||
|
||
### 4.2 启动与常用命令
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
pm2 start ecosystem.config.cjs
|
||
pm2 save
|
||
```
|
||
|
||
常用运维：
|
||
|
||
| 命令 | 作用 |
|
||
|------|------|
|
||
| `pm2 status` | 查看进程状态 |
|
||
| `pm2 logs llm-gateway` | 实时日志 |
|
||
| `pm2 restart llm-gateway` | 重启 |
|
||
| `pm2 stop llm-gateway` | 停止 |
|
||
| `pm2 delete llm-gateway` | 从 PM2 列表移除 |
|
||
|
||
修改代码或依赖后：`pip install …` 完成再执行 `pm2 restart llm-gateway`。
|
||
|
||
---
|
||
|
||
## 5. 不用配置文件时的等价命令
|
||
|
||
若暂时不用 `ecosystem.config.cjs`，需自行写出虚拟环境里 **Python 可执行文件绝对路径**。
|
||
|
||
**Linux 示例：**
|
||
|
||
```bash
|
||
pm2 start /path/to/中转网关/venv/bin/python \
|
||
--name llm-gateway \
|
||
--cwd /path/to/中转网关 \
|
||
--interpreter none \
|
||
-- -m uvicorn main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
**Windows 示例（PowerShell，路径按实际修改）：**
|
||
|
||
```powershell
|
||
pm2 start "C:\path\to\中转网关\venv\Scripts\python.exe" `
|
||
--name llm-gateway `
|
||
--cwd "C:\path\to\中转网关" `
|
||
--interpreter none `
|
||
-- -m uvicorn main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
然后通过 PM2 设置环境变量（任选其一）：
|
||
|
||
```bash
|
||
pm2 restart llm-gateway --update-env
|
||
```
|
||
|
||
或在启动前于终端导出 `JWT_SECRET`、`UPSTREAM_URL` 后再 `pm2 start …`（注意：`--update-env` 与持久化策略以当前 PM2 版本文档为准）。
|
||
|
||
---
|
||
|
||
## 6. 开机自启
|
||
|
||
PM2 保存当前进程列表后，生成并启用开机脚本：
|
||
|
||
```bash
|
||
pm2 save
|
||
pm2 startup
|
||
```
|
||
|
||
终端会打印一行以 `sudo` 开头的命令，**复制执行**即可完成 systemd（Linux）或对应平台的自启配置。Windows 可使用 **pm2-windows-service** 或任务计划程序配合 `pm2 resurrect`，按环境选用。
|
||
|
||
---
|
||
|
||
## 7. 日志与配置文件
|
||
|
||
| 项 | 说明 |
|
||
|------|------|
|
||
| PM2 日志 | `pm2 logs llm-gateway`，默认在 `~/.pm2/logs/` |
|
||
| 账号与 API Key | **`gateway.json`**（或 `GATEWAY_CONFIG` 指向的文件），含明文密码，请限制权限（如 `chmod 600`），勿提交到版本库 |
|
||
|
||
---
|
||
|
||
## 8. 反向代理（可选）
|
||
|
||
对外只暴露 443/80 时，可用 Nginx/Caddy 把域名反向代理到 `http://127.0.0.1:8000`，并配置 TLS。此时上游 **`UPSTREAM_URL`** 仍指向本机大模型地址，与网关对外端口无关。
|
||
|
||
---
|
||
|
||
## 9. 故障排查
|
||
|
||
1. **`pm2 logs` 中报 ModuleNotFoundError**
|
||
确认 PM2 使用的解释器是 **`venv` 内的 python**，且已在同一 venv 中执行 `pip install -r requirements.txt`。
|
||
|
||
2. **502 / 上游连接失败**
|
||
检查大模型是否监听 `UPSTREAM_URL`，防火墙与内网穿透是否正常。
|
||
|
||
3. **修改 `JWT_SECRET` 后旧登录失效**
|
||
属预期行为，用户需重新登录网页端。
|
||
|
||
---
|
||
|
||
## 10. 小结
|
||
|
||
1. 创建 venv 并安装 `requirements.txt`。
|
||
2. 配置 **`JWT_SECRET`**（及可选 **`UPSTREAM_URL`**）。
|
||
3. `pm2 start ecosystem.config.cjs` → `pm2 save` → `pm2 startup`（按需）。
|
||
|
||
进程名 **`llm-gateway`** 与 `ecosystem.config.cjs` 中 `name` 字段一致，便于 `pm2 restart llm-gateway` 等操作。
|