本文档专门用于说明如何把 pioneer-portal 迁移到远端服务器，并说明：
- 迁移后哪些配置必须修改
- 如何与远端已有的
cli-proxy-api协同工作 - 什么情况下需要修改远端 CLIProxy
- 上线后的推荐部署方式与排障方法
1.1 pioneer-portal 一定要改什么
迁移到远端后，至少需要修改这些内容：
- Django 环境变量
- 数据库连接信息
- 允许访问的域名 / IP
- 供门户拉取 usage 的 CLIProxy 管理接口地址
- 静态文件与运行方式（开发模式不能直接当生产模式长期跑）
1.2 远端的 cli-proxy-api 要不要改
分情况：
- 如果远端 CLIProxy 已经稳定运行，并且你只想让门户读取它的 usage / 管理接口，通常不用改 CLIProxy 主程序本体。
- 你只需要确认：
- CLIProxy 正在运行
- 管理接口可访问
- 返回的数据格式和门户当前读取逻辑兼容
- 只有在以下情况才需要改远端 CLIProxy：
- 管理接口端口不对
- 管理接口路径不是门户当前使用的路径
- 远端没开启管理接口
- usage 返回格式和门户解析逻辑不一致
也就是说，优先改门户配置，不要先动远端 CLIProxy 代码。
建议远端至少具备：
- Linux 服务器
- Python 3.10+ 或 3.11
- PostgreSQL
- Nginx（推荐）
- systemd（推荐）
你计划把 pioneer-portal 推到 GitHub，再拉到远端，这个流程是对的。
建议远端目录类似：
/home/youruser/
├── pioneer-portal/
├── cli-proxy/
│ ├── cli-proxy-api
│ └── config.yaml
└── venvs/
└── pioneer-portal-venv/
其中：
pioneer-portal放新门户代码cli-proxy-api继续作为远端代理主程序- Python 虚拟环境建议单独放，不要再放旧目录里，避免以后误删
在远端服务器执行：
git clone <你的 GitHub 仓库地址> pioneer-portal
cd pioneer-portalpython3 -m venv /home/youruser/venvs/pioneer-portal-venv
source /home/youruser/venvs/pioneer-portal-venv/bin/activate
pip install -r requirements.txt如果仓库中有 .env.example，先复制：
cp .env.example .env然后重点修改以下配置。
4. 迁移后 pioneer-portal 必须改的配置
至少保证这些变量正确：
DJANGO_SECRET_KEYDJANGO_DEBUG=FalseDJANGO_ALLOWED_HOSTSDJANGO_CSRF_TRUSTED_ORIGINS
例如：
DJANGO_SECRET_KEY=换成你自己的强随机字符串
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=your-domain.com,server-ip,127.0.0.1
DJANGO_CSRF_TRUSTED_ORIGINS=https://your-domain.com,http://server-ip如果这些不改，常见问题包括：
- 无法通过域名访问
- CSRF 403
- Debug 页面暴露
你需要让远端门户连接自己的 PostgreSQL，而不是本地开发数据库。
确保：
- 数据库已创建
- 用户有权限
.env中数据库主机、端口、库名、用户名、密码正确
迁移后执行：
python manage.py migrate
python manage.py createsuperuser如果你已经有数据迁移方案，也可以导入旧数据后再启动。
从你现在的报错看，门户会去请求：
http://127.0.0.1:8317/v0/management/usage
这说明 fetch_cliproxy_usage_records() 依赖一个 CLIProxy 管理接口地址。
所以迁移后必须确认两件事：
- 远端 CLIProxy 的管理接口是不是也监听在
127.0.0.1:8317 - 路径是不是
/v0/management/usage
如果 CLIProxy 和门户在同一台服务器：
- CLIProxy 管理接口建议继续只监听本机，例如：
127.0.0.1:8317 - 门户服务本机访问它即可
如果 CLIProxy 和门户在不同服务器：
- 需要把门户配置改成 CLIProxy 所在服务器地址
- 同时做好防火墙 / 反向代理 / 白名单控制
优先改门户读取地址，不优先改 CLIProxy 程序。
如果远端 CLIProxy 满足以下条件，就不需要修改 CLIProxy：
- 代理功能正常
- 管理接口可用
- 访问下面地址有返回：
curl http://127.0.0.1:8317/v0/management/usage- 返回数据字段能被
usage/services.py正常解析
这种情况下，你只需要让 pioneer-portal 对准这个地址即可。
只有这些情况才建议改远端 CLIProxy：
表现：
- 门户一直报连接拒绝
curl管理接口失败
这时要检查远端 CLIProxy 的配置文件 config.yaml 是否开启管理接口。
如果远端实际监听的是其他端口，比如 9000，那就：
- 要么改门户配置
- 要么改 CLIProxy 配置统一端口
优先建议改门户配置。
如果远端提供的是别的路径，而不是：
/v0/management/usage
那就需要：
- 修改门户的对接地址
- 或修改 CLIProxy 的管理路由
仍然建议优先改门户。
如果远端 CLIProxy 版本和你现在本地用来适配的版本不同，返回字段可能不一样。
这时通常要调整的是门户里的解析逻辑：
而不是先去动 CLIProxy 主体。
先在远端确认代理服务活着：
ps -ef | grep cli-proxy-api
ss -ltnp | grep 8317然后验证管理接口：
curl http://127.0.0.1:8317/v0/management/usage说明 CLIProxy 基本不用动。
说明：
- 要么 CLIProxy 没启动
- 要么管理接口没开
- 要么端口不对
这个时候才去看远端的 config.yaml。
python manage.py migrate
python manage.py check
python manage.py createsuperuser如果 python manage.py check 能过，说明 Django 项目基础没问题。
登录门户后，观察：
如果这里报错，优先看：
- CLIProxy 管理接口连通性
- 门户环境变量中的管理接口地址
不要长期直接使用：
python manage.py runserver 0.0.0.0:8002推荐使用：
- Gunicorn + systemd
- Nginx 反向代理
gunicorn lab_portal.wsgi:application --bind 127.0.0.1:8002Nginx 对外监听 80/443，然后反向代理到：
127.0.0.1:8002
静态文件由 Nginx 直接托管。
推荐：可以在同机部署，但分目录管理。
例如：
- CLIProxy：
/opt/cliproxy/ - Portal：
/opt/pioneer-portal/
这样好处是：
- 门户升级不影响 CLIProxy 主程序
- CLIProxy 升级也不影响门户代码
- 出问题时更容易排查
下面是一份真正落地时的 checklist：
- GitHub 代码已拉到远端
- Python 虚拟环境已建立
- 依赖已安装
-
.env已配置 - PostgreSQL 已准备好
- 执行过
python manage.py migrate - 执行过
python manage.py check - 已创建管理员账号
- 静态文件已处理
- Gunicorn / systemd / Nginx 已配置
-
cli-proxy-api正在远端运行 -
config.yaml配置正确 - 管理接口可以从门户所在机器访问
-
/v0/management/usage返回正常
最终建议非常明确：
先做这些：
- 启动远端 CLIProxy
- 确认管理接口地址
- 修改门户配置去对接它
优先改：
因为这属于适配层，风险更小。
只有当远端版本过老、根本不提供当前所需管理能力时，再考虑升级或修改 CLIProxy。
你把代码传上远端后，建议按下面顺序测试：
cd /path/to/pioneer-portal
source /path/to/venv/bin/activate
python manage.py check
python manage.py migrate
curl http://127.0.0.1:8317/v0/management/usage
python manage.py runserver 0.0.0.0:8002然后浏览器验证：
//accounts/login//dashboard/public//dashboard/admin//usage/sync/status/
结合你当前本地现象，远端最容易出现的是：
表现：
/usage/sync/status/报 500- 日志里出现
Connection refused
表现：
- 页面能打开
- 仪表盘没数据或自动同步报错
表现：
- 登录页可开
- 登录 / POST 操作失败
一般是：
DJANGO_ALLOWED_HOSTSDJANGO_CSRF_TRUSTED_ORIGINS
没配好。
表现：
- 页面有 HTML，但没样式
- 图片不显示
这通常是 Nginx 静态文件或 Django static 配置没处理好。
最推荐你采用下面的架构：
- 远端保留已有
cli-proxy-api - 新建独立目录部署
pioneer-portal - 门户通过本机地址读取 CLIProxy 管理接口
- 不改 CLIProxy 主逻辑，优先改门户适配配置
- 用 Gunicorn + Nginx 托管门户
这套方式风险最低，也最容易持续维护。
把 pioneer-portal 移植到远端后，重点修改的是门户的环境变量、数据库配置和 CLIProxy 管理接口地址；远端 cli-proxy-api 通常不需要改代码，只需要确认它的管理接口确实可用。