dekun/openai_node

Fork 0

Files

T

dekun a98b24fa32 first commit

2026-05-19 02:05:00 +08:00

5.3 KiB

Raw Blame History

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

cd /path/to/中转网关
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -U

Windows（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 指定配置文件绝对路径。

确认可手动启动：

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 修改配置

用编辑器打开 ecosystem.config.cjs。
在 env 里填写 JWT_SECRET（必填），按需修改 UPSTREAM_URL。
若端口冲突，可在 args 中把 8000 改成其它端口。

4.2 启动与常用命令

在项目根目录执行：

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 示例：

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，路径按实际修改）：

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 设置环境变量（任选其一）：

pm2 restart llm-gateway --update-env

或在启动前于终端导出 JWT_SECRET、UPSTREAM_URL 后再 pm2 start …（注意：--update-env 与持久化策略以当前 PM2 版本文档为准）。

6. 开机自启

PM2 保存当前进程列表后，生成并启用开机脚本：

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. 故障排查

pm2 logs 中报 ModuleNotFoundError
确认 PM2 使用的解释器是 venv 内的 python，且已在同一 venv 中执行 pip install -r requirements.txt。
502 / 上游连接失败
检查大模型是否监听 UPSTREAM_URL，防火墙与内网穿透是否正常。
修改 JWT_SECRET 后旧登录失效
属预期行为，用户需重新登录网页端。

10. 小结

创建 venv 并安装 requirements.txt。
配置 JWT_SECRET（及可选 UPSTREAM_URL）。
pm2 start ecosystem.config.cjs → pm2 save → pm2 startup（按需）。

进程名 llm-gateway 与 ecosystem.config.cjs 中 name 字段一致，便于 pm2 restart llm-gateway 等操作。

5.3 KiB Raw Blame History Unescape Escape