小氢云极曈：宝塔二进制部署

本文面向「已拿到 Linux 安装包、准备在宝塔服务器上跑 jitong-service 单文件」的运维与开发者。从宝塔面板是什么、左侧菜单干什么，到数据库、进程守护、Nginx 反代、SSL、排错，逐步拆解。

写在前面：你将得到什么

部署完成后，你应当能：

1. 用浏览器打开 https://你的域名，进入已嵌入二进制的管理后台；
2. 在被监控网站里嵌入采集脚本，数据写入 ClickHouse；
3. 服务崩溃或服务器重启后，进程守护自动拉起 jitong-service；
4. 公网只暴露 80/443（及可选的采集端口），API/WebSocket 走 Nginx 反代，不直接裸露。

本系统后端是 Go 编译的单体二进制 jitong-service（cmd/allinone），内含采集、查询 API、WebSocket、管理端静态资源，不需要在服务器上再装 Node、PHP 或单独部署前端。

第一部分：认识宝塔面板（BT Panel）

1.1 宝塔是什么

宝塔 Linux 面板是一款 Web 化的服务器运维工具。它把常见的 Linux 命令（装 Nginx、绑域名、配 SSL、开防火墙、看磁盘）封装成左侧菜单里的可视化功能。

对你而言，宝塔主要承担四件事：

1.2 登录后左侧菜单速览（11.x / 10.x 通用）

不同小版本菜单名称可能略有差异，逻辑一致：

• 首页：CPU、内存、磁盘、网络概览；适合确认机器是否吃得消（建议 4GB+ 内存，生产 8GB 更稳）。
• 网站：绑定域名 → Nginx 配置 → 反向代理 → SSL。
• 数据库：若用宝塔自带的 MySQL，本项与极曈无关；我们 PG/CH 走 Docker。
• Docker / 容器：应用商店部署 PG、Redis、ClickHouse、NATS。
• 文件：/www/wwwroot/jitong 目录操作的主战场。
• 软件商店：安装 Nginx、进程守护管理器（Supervisor 插件）。
• 安全：系统防火墙、SSH 端口、可选「系统加固」。
• 计划任务：备份脚本、cron 清理日志（可选）。
• 终端：SSH 命令行（装 Docker、测端口、chmod +x）。

1.3 宝塔与「二进制部署」的关系

很多人误以为宝塔只能跑 PHP。实际上：

• PHP 站点：宝塔擅长；
• Go/Java 二进制：宝塔不负责编译，只负责 放文件 + 守护进程 + Nginx 反代，这正是本文路线。

数据流可以记成：

用户浏览器 → 443/80（Nginx，宝塔「网站」） → 127.0.0.1:8081（jitong-service 查询 + 管理端） → 127.0.0.1:8082（WebSocket，需 Upgrade 头） → 127.0.0.1:8083（埋点采集，也可单独域名）

jitong-service（单进程） → PostgreSQL / Redis / ClickHouse / NATS（建议本机 Docker，127.0.0.1 连接）

第二部分：服务器与宝塔安装

2.1 硬件与系统

2.2 安装宝塔（未装面板时）

SSH 登录服务器后执行官方脚本（以官网文档为准，以下为常见万能脚本示例）：

if [ -f /usr/bin/curl ]; then
  curl -sSO https://download.bt.cn/install/install_panel.sh
else
  wget -O install_panel.sh https://download.bt.cn/install/install_panel.sh
fi
bash install_panel.sh

安装结束终端会打印：

• 外网面板地址：http://IP:8888/xxxxxxxx
• 用户名 / 密码

务必立刻：

1. 浏览器登录，按向导绑定宝塔账号（可选但推荐）；
2. 面板设置 → 修改默认端口、开启面板 SSL、限制面板 IP（安全加固）；
3. 在 安全 里放行你需要的端口（至少 SSH、80、443、8888 或你改过的面板端口）。

2.3 安装 Nginx（必做）

软件商店 → 搜索 Nginx → 安装稳定版。

后面「网站」功能依赖 Nginx。若已装 OpenLiteSpeed 等，也可反代，但本文以 Nginx 为例（与宝塔文档一致）。

2.4 安装 Docker（推荐，用于数据库）

路径：Docker / 容器 → 首次进入按提示安装 Docker 引擎。

也可命令行：

curl -fsSL https://get.docker.com | bash
systemctl enable docker
systemctl start docker

第三部分：用宝塔部署四大依赖（Docker）

极曈单体二进制不自带数据库，需事先准备好：

• PostgreSQL：用户、订单、配置、租户等关系数据；
• Redis：缓存、在线状态、实时相关；
• ClickHouse：海量埋点事件分析；
• NATS JetStream：采集到写入之间的消息队列。

下面默认全部跑在同一台机的 Docker 里，应用配置里用 127.0.0.1 连接。

3.1 PostgreSQL

方式 A：宝塔 Docker 应用商店

1. Docker → 应用商店 → 搜索 PostgreSQL → 安装；
2. 建议配置：

方式 B：命令行

mkdir -p /www/server/postgresql/data
docker run -d \
  --name jitong-postgres \
  --restart always \
  -e POSTGRES_USER=tongji \
  -e POSTGRES_PASSWORD='你的强密码' \
  -e POSTGRES_DB=tongji \
  -p 5432:5432 \
  -v /www/server/postgresql/data:/var/lib/postgresql/data \
  postgres:16-alpine

验证：

docker exec -it jitong-postgres psql -U tongji -d tongji -c "SELECT 1;"

PostgreSQL 15+ 若报 permission denied for schema public，需对业务用户授权 public schema（首次启动日志里会有 hint）。

3.2 Redis

商店安装或：

mkdir -p /www/server/redis/data
docker run -d \
  --name jitong-redis \
  --restart always \
  -p 6379:6379 \
  -v /www/server/redis/data:/data \
  redis:7-alpine \
  redis-server --requirepass '你的Redis密码' --appendonly yes

验证：docker exec -it jitong-redis redis-cli -a 你的Redis密码 ping → PONG。

3.3 ClickHouse

ClickHouse 需要能 建表、INSERT、复杂 SELECT（含 JSON 函数等）。

商店部署时注意：

命令行示例：

mkdir -p /www/server/clickhouse/data
docker run -d \
  --name jitong-clickhouse \
  --restart always \
  -e CLICKHOUSE_USER=admin \
  -e CLICKHOUSE_PASSWORD='你的CH密码' \
  -e CLICKHOUSE_DB=default \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  -p 19000:9000 \
  -p 8123:8123 \
  -v /www/server/clickhouse/data:/var/lib/clickhouse \
  clickhouse/clickhouse-server:latest

验证：

docker exec -it jitong-clickhouse clickhouse-client -u admin --password '你的CH密码' -q "SELECT 1"

3.4 NATS（JetStream，必开）

mkdir -p /www/server/nats/jetstream
docker run -d \
  --name jitong-nats \
  --restart always \
  -p 4222:4222 \
  -p 8222:8222 \
  -v /www/server/nats/jetstream:/data/jetstream \
  nats:latest \
  -js -sd /data/jetstream

宝塔手动建容器时：执行命令填 -js -sd /data/jetstream，挂载目录 /www/server/nats/jetstream:/data/jetstream。

验证：docker exec jitong-nats nats server info 输出里应有 JetStream: Enabled。

3.5 一键检查四个容器

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | grep jitong

四个都在 Up 再往下走。

第四部分：部署 jitong-service 二进制

4.1 获取安装包

官方渠道（如 auth-v1.ithxs.com 下载中心）获取：

• jitong-service-vX.Y.Z-install.zip（首次安装：含二进制 + config/ + start.sh / stop.sh）

解压后典型结构：

/www/wwwroot/jitong/ ├── jitong-service # Linux amd64/arm64 可执行文件 ├── config/ │ └── config.yaml ├── start.sh ├── stop.sh └── data/ # 需自建，放 WAL、上传等

4.2 在宝塔创建目录并上传

1. 文件 → 进入 /www/wwwroot → 新建文件夹 jitong；
2. 上传 zip → 右键 解压 → 确认根目录直接是 jitong-service，而不是多套一层目录；
3. 新建 data 目录。

4.3 赋予执行权限

终端或 SSH：

cd /www/wwwroot/jitong
chmod +x jitong-service start.sh stop.sh
file jitong-service   # 应显示 ELF 64-bit LSB executable

若报 cannot execute: required file not found：

• 常见原因：把 macOS 版二进制传上了 Linux，或架构不对（amd64 vs arm64）；
• 处理：在开发机用 build_backend.sh 重新打 linux / linux-arm64 包再上传。

4.4 理解 config.yaml（逐项嚼碎）

路径：/www/wwwroot/jitong/config/config.yaml。下面说明与本机 Docker 部署对应的改法。

app

• version：安装包已写入，一般不用手改。
• data_dir（可选）：指定数据根，如 /www/wwwroot/jitong/data；不填则用系统缓存目录下的 jitong。

server（监听端口，被 Nginx 反代）

注意：改端口后，下文 Nginx proxy_pass 必须同步改。

nats

nats:
  url: "nats://127.0.0.1:4222"
  stream: "JITONG_EVENTS"
  subject_raw: "jitong.events.raw"

clickhouse

clickhouse:
  addr: "127.0.0.1:19000"   # 对应 Docker 19000:9000
  db: "default"
  user: "admin"
  password: "与容器一致"

postgres

postgres:
  dsn: "postgres://tongji:密码@127.0.0.1:5432/tongji?sslmode=disable"

redis

redis:
  addr: "127.0.0.1:6379"
  password: "与容器一致"
  db: 0

auth（生产必改）

auth:
  jwt_secret: "至少32位随机字符串"
  jwt_access_ttl: "24h"

也可用环境变量 JWT_SECRET 覆盖（见 internal/config）。

collector

• wal_path：可设为 /www/wwwroot/jitong/data/collector.wal，采集失败时本地容灾。

bootstrap（首次管理员）

库中无管理员时，可用配置或环境变量：

• BOOTSTRAP_ADMIN_ACCOUNT / BOOTSTRAP_ADMIN_PASSWORD

否则默认账号见模板注释（上线务必改掉）。

log

生产建议 level: "info"，排错时临时 debug。

在宝塔 文件 里双击 yaml 编辑 → 保存。

4.5 前台试运行（必做）

cd /www/wwwroot/jitong
./jitong-service

成功时类似：

postgres schema migrate ... 采集服务监听 :8083 查询服务监听 :8081 WebSocket 监听 :8082

若失败，看报错关键词：

确认无误后 Ctrl+C 停掉，改由守护进程拉起。

第五部分：宝塔「进程守护管理器」常驻服务

比 nohup ./start.sh 更稳的是 Supervisor（宝塔插件：进程守护管理器）。

5.1 安装插件

软件商店 → 搜索 进程守护管理器 → 安装。

5.2 添加守护进程

点击 添加守护进程，建议填写：

不要用 start.sh 里 nohup 包一层给 Supervisor——Supervisor 自己会拉进程，双层容易误判。

5.3 日志

插件里可看 stdout/stderr；同时建议：

tail -f /www/wwwroot/jitong/app.log   # 若你用 start.sh 测过

5.4 开机自启

守护进程配置正确且状态为 运行中，重启服务器后应自动恢复。可在面板 重启服务器 做一次验收。

5.5 备选：systemd

若不用 Supervisor，可建 /etc/systemd/system/jitong.service：

[Unit]
Description=小氢云极曈监控 jitong-service
After=network.target docker.service

[Service]
Type=simple
WorkingDirectory=/www/wwwroot/jitong
ExecStart=/www/wwwroot/jitong/jitong-service
Restart=on-failure
RestartSec=5
Environment=CONFIG_FILE=/www/wwwroot/jitong/config/config.yaml

[Install]
WantedBy=multi-user.target

然后：

systemctl daemon-reload
systemctl enable --now jitong
systemctl status jitong

宝塔与 systemd 二选一即可，避免重复拉起两个进程。

第六部分：宝塔「网站」+ Nginx 反向代理

管理端已打进二进制，对外只需一个域名指向 8081，WebSocket 走 8082，采集可走同域路径或子域。

6.1 添加站点

1. 网站 → 添加站点；
2. 域名：monitor.example.com（换成你的）；
3. 根目录：/www/wwwroot/jitong（纯静态即可，实际页面由 Go 提供）；
4. PHP：纯静态 / 不创建 PHP。

6.2 配置反向代理（图形界面）

站点 → 设置 → 反向代理 → 添加反向代理：

可先加一条「主站」：

• 代理名称：jitong-api
• 目标 URL：http://127.0.0.1:8081
• 发送域名：$host
• 内容替换：留空

但 WebSocket 和 采集路径 往往要单独 location，更推荐直接改配置文件。

6.3 推荐：完整 Nginx 配置片段

站点 → 设置 → 配置文件，在 server { ... } 内合并（注意勿重复 listen 冲突）：

    # 管理后台 + API（单体二进制 query 端口）
    location / {
        proxy_pass http://127.0.0.1:8081;
        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_connect_timeout 60s;
        proxy_read_timeout 120s;
    }

    # WebSocket（实时在线等）
    location /ws {
        proxy_pass http://127.0.0.1:8082;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 3600s;
    }

    # 埋点采集（按你实际路由，常见 /collect、/t.gif 等）
    location /collect {
        proxy_pass http://127.0.0.1:8083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /t.gif {
        proxy_pass http://127.0.0.1:8083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

保存后 重载配置。宝塔会执行 nginx -t，失败则根据提示改语法。

6.4 SSL 证书

站点 → SSL → Let's Encrypt → 填邮箱 → 申请 → 开启 强制 HTTPS。

证书只挂在 Nginx；Go 进程仍监听内网 HTTP 端口，这是正常架构。

6.5 采集脚本里的域名

登录后台 → 站点管理 → 复制追踪代码，把脚本地址改成你的公网域名，例如：

<script>
(function () {
  var s = document.createElement('script');
  s.src = 'https://monitor.example.com/collect/jitong.js';
  s.async = true;
  document.head.appendChild(s);
})();
</script>

确保 location /collect 已反代到 8083，且防火墙允许 HTTPS 出站访问。

第七部分：防火墙与安全

7.1 宝塔「安全」防火墙

建议：

7.2 云厂商安全组

阿里云 / 腾讯云等控制台还要放行 80/443，与宝塔防火墙是两层，都要开。

7.3 生产安全清单

• 修改 jwt_secret、数据库密码、Redis/CH 密码
• 修改默认管理员密码
• 面板改端口 + 绑定访问 IP
• 定期备份 PG 与 config.yaml、data/
• gin_mode: release，关闭不必要的 debug 接口

第八部分：验收与日常运维

8.1 本机探测

curl -s http://127.0.0.1:8081/healthz
curl -I http://127.0.0.1:8081/

8.2 域名访问

浏览器打开 https://monitor.example.com，应出现登录页；首次按向导创建管理员。

8.3 看指标

curl -s http://127.0.0.1:8081/metrics   # Prometheus，可按需限制访问

8.4 升级（仅替换二进制）

1. 宝塔 进程守护 里停止 jitong；
2. 备份：cp jitong-service jitong-service.bak；
3. 上传 jitong-service-vX.Y.Z-update.zip 解压覆盖二进制；
4. chmod +x jitong-service；
5. 启动守护进程；
6. 后台也可用「在线升级」功能（若已接授权站）。

不要覆盖你已改好的 config/config.yaml，除非 release note 要求新增字段。

8.5 备份（计划任务）

在 计划任务 添加 Shell，每日备份：

• docker exec jitong-postgres pg_dump ...
• 打包 /www/wwwroot/jitong/config 与 data

第九部分：常见问题（嚼碎版）

Q1：面板里网站 502 Bad Gateway

1. jitong-service 是否在跑（守护进程状态）；
2. 127.0.0.1:8081 能否 curl；
3. Nginx 错误日志：网站 → 日志 → 错误日志；
4. 是否改了端口却未改 proxy_pass。

Q2：WebSocket 连不上

必须单独 location /ws 且含 Upgrade、Connection；不能用普通 HTTP 反代规则糊在一起。

Q3：有 PV 但报表为空

查 NATS、ClickHouse 容器日志；看采集请求是否 200；浏览器 Network 看 /collect 是否打到正确域名。

Q4：二进制 Permission denied

chmod +x；SELinux 环境可对目录 chcon 或临时 setenforce 0 试排（生产用正确上下文）。

Q5：Supervisor 报「进程结束太快」

说明启动命令错或二进制立刻崩溃；前台 ./jitong-service 看 stderr。

Q6：宝塔 start.sh 与文档不一致

打包脚本生成的 start.sh 用 command -v nohup，避免硬编码 /bin/nohup 在部分系统不存在。生产推荐 进程守护 直接跑二进制。

第十部分：端口与架构一图读懂

                ┌─────────────────────────────────────┐
                │           宝塔面板 (8888)            │
                │  文件 / 网站 / Docker / 进程守护      │
                └─────────────────────────────────────┘
                                  │

Internet ──► :443 Nginx (宝塔网站) ──┼──► :8081 jitong-service (API+Admin) │ ├──► :8082 WebSocket │ └──► :8083 Collector │ └──► Docker 127.0.0.1 ├── 5432 PostgreSQL ├── 6379 Redis ├── 19000 ClickHouse └── 4222 NATS JetStream

结语

宝塔的价值在于：你不需要成为 Linux 专家，也能完成「依赖用 Docker 管好、业务用二进制 + Supervisor 管好、入口用 Nginx + SSL 管好」这条标准生产路径。极曈监控把前后端打进一个 jitong-service，部署面比传统「前端 dist + 后端 jar」更简单，只要把 四个依赖容器 和 一份 config.yaml 配对正确，剩下的就是反代与守护进程这两层皮。

遇到具体报错，优先看：jitong-service 前台输出、Nginx 错误日志、对应 docker logs jitong-*。

文档版本：2.0（二进制 + 宝塔嚼碎版）
适用产品：小氢云极曈监控 jitong-service
最后更新：2026-06-01