#最新

OneHub 中转会话绘图系统【小白安装教程】

一、部署方式

OneHub 线上只有一个 Node 服务：

最终访问流程：

用户浏览器 -> 域名 Nginx -> http://127.0.0.1:3000 -> OneHub

二、服务器要求

建议配置：

• Linux 服务器，建议 2 核 4G 起步。
• Node.js 20 或 22。
• MySQL 8.x。
• Redis 7.x。
• Nginx。

pnpm 和 PM2 如果没有安装，install.sh 会尝试自动安装。

生产目录建议统一使用：

/www/wwwroot/onehub

三、宝塔 / 1Panel 一键安装

1. 安装基础软件

在面板里安装：

• Nginx
• MySQL 8.x
• Redis
• Node.js 20 或 22

进入面板终端确认：

node -v
npm -v

看到 Node.js v20.x 或 v22.x 就可以。

2. 上传并解压发布包

把 onehub-release-时间戳.tar.gz 上传到服务器，然后执行：

mkdir -p /www/wwwroot/onehub
cd /www/wwwroot/onehub
tar -xzf /上传目录/onehub-release-时间戳.tar.gz --strip-components=1

如果你是在面板文件管理里解压，也要保证 /www/wwwroot/onehub 里面能直接看到：

install.sh
server.cjs
apps
packages
scripts
INSTALL_PANEL.md

如果面板解压后多了一层目录，例如：

/www/wwwroot/onehub/onehub-release-时间戳/install.sh

直接进入这层目录执行也可以，脚本会自动把程序安装到上一层 /www/wwwroot/onehub：

cd /www/wwwroot/onehub/onehub-release-时间戳
bash install.sh

3. 创建数据库并启动 Redis

在面板里创建 MySQL 数据库：

• 数据库名：onehub
• 用户名：建议也填 onehub
• 密码：使用强密码并保存好

确认 Redis 已启动。没有设置 Redis 密码时，安装向导里 Redis 密码留空。

4. 执行一键安装脚本

在终端执行：

cd /www/wwwroot/onehub
bash install.sh

脚本会自动处理：

• 检查发布包是否完整。
• 检查 Node.js 版本。
• 自动安装 pnpm 和 PM2。
• 安装生产依赖。
• 使用 PM2 启动 OneHub 安装向导。
• 打印安装向导访问地址。

5. 打开安装向导

如果暂时没有配置域名，先打开：

http://服务器IP:3000/install

安装向导填写：

点击开始安装。页面会显示安装进度，完成后稍等几秒打开首页。

安装完成后使用默认管理员账号登录：

首次登录后请及时修改默认密码。

临时 IP 安装时，网站前端访问网址 必须写 http://服务器IP:3000，不要写成 https://服务器IP:3000。

四、配置域名反向代理

在宝塔或 1Panel 创建网站，域名填你的正式域名，根目录可以使用一个空目录，例如：

/www/wwwroot/onehub-site

然后添加反向代理：

保存后访问域名即可。

保存后建议打开网站配置，确认反向代理文件里有类似下面的内容：

location ^~ / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

如果看到 proxy_set_header Host 127.0.0.1;，把它改成 proxy_set_header Host $host;。如果看到 proxy_set_header Connection $connection_upgrade; 后 Nginx 检查失败，可以改成 proxy_set_header Connection "upgrade";。

改完后执行：

nginx -t
systemctl reload nginx

如果看到：

404 Not Found
nginx

说明请求还停在 Nginx，没有转发到 OneHub。重点检查：

1. 反向代理目标必须是 http://127.0.0.1:3000，不要写成 https://127.0.0.1:3000。
2. 代理路径必须是 /。
3. 不要把网站根目录指向 /www/wwwroot/onehub/apps/api/public。
4. 如果站点配置里有 location / { try_files ... =404; }，需要改成反向代理。
5. 确认反向代理文件确实在 /www/server/panel/vhost/nginx/proxy/你的域名/ 目录里，并且主站点配置有 include 这批文件。
6. 不要给首页开启缓存；入口页如果返回 304，浏览器可能继续使用旧页面和旧响应头。

确认 Node 服务是否正常：

curl -I http://127.0.0.1:3000
curl -I http://127.0.0.1:3000/install

五、配置 HTTPS

在面板网站 SSL 设置里申请证书，开启 HTTPS。

反向代理目标仍然保持：

http://127.0.0.1:3000

域名和 SSL 配好后，建议修改 /www/wwwroot/onehub/apps/api/.env：

APP_ORIGIN=https://你的域名
ONEHUB_LICENSE_SERVER_URL=https://console.sg65.cn

然后重启：

pm2 restart onehub-api --update-env

六、常用命令

cd /www/wwwroot/onehub

# 查看服务状态
pm2 status

# 查看日志
pm2 logs onehub-api --lines 100

# 重启服务
pm2 restart onehub-api --update-env

# 重新执行一键脚本，脚本会自动检查并修复常见旧进程问题
bash install.sh

# 需要排查时再执行，普通安装/更新不用先跑
bash install.sh doctor

七、以后怎么更新

上传新的 onehub-release-时间戳.tar.gz 到服务器，例如放到 /www/wwwroot/，然后执行：

cd /www/wwwroot/onehub
bash install.sh /www/wwwroot/onehub-release-时间戳.tar.gz

一键脚本会自动判断这是更新，不需要你再运行别的脚本。它会自动备份并恢复 apps/api/.env 和 .onehub，覆盖程序文件，安装依赖，同步数据库，重启 PM2，并检查是否更新到了正确目录。

如果更新后页面表现还是旧版本，先执行：

cd /www/wwwroot/onehub
bash install.sh doctor

它会检查当前目录里的后端文件、PM2 运行目录、3000 端口进程和响应头，直接指出是不是旧进程、旧目录或旧发布包。

如果你已经把新包解压成目录，也可以直接传解压目录：

cd /www/wwwroot/onehub
bash install.sh /www/wwwroot/onehub/onehub-release-时间戳

不要删除服务器上的数据库和 Redis 数据。

八、常见问题

1. bash install.sh 提示 Node.js 版本不对

在面板里安装 Node.js 20 或 22。不要单独执行 apt install npm。

2. 打不开 服务器IP:3000/install

按顺序检查：

pm2 status
pm2 logs onehub-api --lines 100
curl -I http://127.0.0.1:3000/install

如果本机 curl 正常，但浏览器打不开，通常是服务器安全组或防火墙没有放行 3000 端口。配置好域名反向代理后，可以不开放公网 3000。

3. PM2 显示 online 但重启次数一直增加

先重新执行一键脚本，它会自动清理旧的 OneHub 进程：

cd /www/wwwroot/onehub
bash install.sh

如果还是不行，再查看日志：

pm2 logs onehub-api --lines 100

常见原因：

• 端口 3000 已被旧进程占用。
• 解压目录不对，server.cjs 不在 /www/wwwroot/onehub。
• apps/api/dist/apps/api/src/main.js 不存在，发布包不完整。
• 之前安装失败留下了 .onehub/installed.json。

4. 安装向导提示数据库连接失败

检查 MySQL 是否启动，数据库名、用户名、密码是否正确。一般本机 MySQL 主机填：

127.0.0.1

5. 安装向导提示 Redis 连接失败

检查 Redis 是否启动，端口是否是 6379，是否设置了密码。没有密码就留空。

6. 页面资源变成 HTTPS 加载失败

临时 IP 访问时，APP_ORIGIN 和安装向导里的访问网址必须使用：

http://服务器IP:3000

不要写成：

https://服务器IP:3000

7. 修改配置后不生效

修改 /www/wwwroot/onehub/apps/api/.env 后优先执行一键脚本：

cd /www/wwwroot/onehub
bash install.sh

脚本会重新读取配置、安装缺失依赖并重启服务。只想单纯重启时再执行：

pm2 restart onehub-api --update-env

8. 端口被占用

查看占用：

lsof -i:3000

如果是旧的 OneHub 进程，执行：

cd /www/wwwroot/onehub
bash install.sh

新手建议优先保持 3000 端口，不要频繁改端口。