现象

新项目启动时，日志里出现类似错误：

ERROR: permission denied for schema public (SQLSTATE 42501)

同时能看到程序在执行自动建表，例如：

CREATE TABLE "lh_users" (...)

很多人第一反应是：宝塔里不是已经创建了数据库和用户吗？为什么还不行？

错误是什么意思

一句话：

数据库已经连上了，但当前业务用户没有在 public 模式下创建表的权限。

• 能连接：账号密码、库名一般没问题
• 建不了表：CREATE TABLE 被 PostgreSQL 拒绝
• 错误码 42501：权限不足（insufficient_privilege）

这和「表结构写错」通常无关，是权限问题。

为什么宝塔里创建了还有用？

宝塔「添加数据库」一般只会：

1. 创建数据库
2. 创建用户
3. 给这个用户连库、使用该库的基本权限

但从 PostgreSQL 15 开始，public 模式默认不再给普通用户 CREATE 权限。

所以会出现这种组合：

• 宝塔里库、用户都建好了
• 程序能连上
• 自动迁移建表仍然报 permission denied for schema public

结论：在宝塔创建数据库是必要的，但不等于已经有建表权限。

在宝塔哪里处理

进入：软件商店 → PostgreSQL 管理器 → 数据库列表

找到你的业务库（例如库名 login、用户 login），可以先点右侧「权限」看有没有所有者设置。

如果面板里不好改，就用终端补授权（推荐）。

终端怎么连 PostgreSQL

1. 注意：直接敲 psql 常会失败

sudo -u postgres psql
# sudo: psql: command not found

宝塔安装的 PostgreSQL，客户端通常不在系统 PATH 里，要用完整路径。

2. 确认 psql 位置

ls /www/server/pgsql/bin/psql

如果存在，用下面方式连接超级用户：

/www/server/pgsql/bin/psql -U postgres -h 127.0.0.1 -p 5432

密码在 PostgreSQL 管理器页面点「Postgres密码」查看或重置。

如果路径不对，可搜索：

find /www -name psql 2>/dev/null

3. 给业务用户补权限

以库名 login、用户 login 为例：

\c login
GRANT USAGE, CREATE ON SCHEMA public TO login;
ALTER DATABASE login OWNER TO login;
\q

把上面的 login 换成你自己的库名和用户名。

4. 验证是否修好（可选）

/www/server/pgsql/bin/psql -U login -h 127.0.0.1 -d login -p 5432

进入后执行：

CREATE TABLE test_perm(id int);
DROP TABLE test_perm;
\q

能建能删，说明权限已经够了。然后再启动项目，自动建表一般就能过。

常见误区

小结

遇到：

permission denied for schema public (SQLSTATE 42501)

优先检查：

1. 业务用户是不是该库的 owner
2. 是否已对 public 授予 USAGE, CREATE
3. 授权后重新启动项目

按上面做完，新项目自动建表这一步通常就能正常通过。

如果你用的是彩虹自助下单系统（Plus），又想对接小氢云商城当货源，可以用这款官方风格的扩展插件：名称就叫「小氢云」，装进彩虹的对接扩展目录即可使用。

一句话：彩虹当前台卖货，小氢云当货源；支持拉分类/商品、余额下单、卡密回传、定时查单同步。

适合谁

• 已经在跑彩虹站，想接小氢云上的货

• 需要批量对接、自动下单、卡密自动回填

• 不想改彩虹核心文件，只加一个插件目录

插件放哪里

把整个插件文件夹放到彩虹站的扩展目录：

includes/core/extend/Xiaoqingyun/

目录内至少包含：

• config.php：插件名称、类型、账号字段说明

• Xiaoqingyun.php：下单、查单、拉商品、价格监控等逻辑

放到位后，后台「对接站点 / 社区」里就能看到「小氢云」选项（无需改 shopbatch 核心代码）。

怎么配置社区

鉴权走小氢云原生同系统对接协议：请求头带 Keys、Timestamp、Sign（签名规则与小氢云文档一致）。

能做什么

1. 拉分类 / 商品：对接站点里同步分类与商品列表，批量铺货可用。

2. 商品详情：同步名称、价格、库存、最小/最大下单量、下单输入框等。

3. 余额下单：买家在彩虹下单后，插件用对接密钥向小氢云创建订单。

4. 卡密回传：小氢云下单成功若立刻返回卡密，会写回彩虹订单。

5. 订单同步：插件开启定时查单，按商户单号拉取状态与卡密（彩虹扩展插件本身没有异步回调入口，状态主要靠查单同步）。

对接接口一览

使用注意

• 密钥填错或站点地址少了协议头，会导致签名失败、下单失败。

• 商品要对上小氢云侧的商品 ID（对接商品 ID）。

• 库存、最小/最大购买数量以小氢云商品详情为准；若后台某字段仍为空，可先点一次「获取商品信息」再保存。

• 异步通知：小氢云侧支持下单传回调地址，但彩虹对接插件框架没有标准回调接收口，当前推荐开启订单同步（cron 查单）。

小结

「小氢云」彩虹对接插件把两套系统用原生对接协议连起来：装目录、填网址和密钥、同步商品，就能卖小氢云上的货。适合想快速扩货、又不想动彩虹核心的站长。

需要安装包或更新日志时，可在博客「小氢云」分类下继续关注后续说明。

AllinSSL × CDNFly V6 插件使用教程

本文说明 cdnfly-v6 插件：把 AllinSSL 申请到的证书自动上传到 CDNFly V6，并按网站名批量切换 HTTPS 证书。

重点写清两件事：

• 宝塔 Docker（DK） 安装时，插件放哪、怎么用
• 原生 Linux 安装时，插件放哪、怎么用

插件下载

cdnfly-v6 安装包（Linux amd64）网盘地址：

https://pan.ithxs.com/p/ithxs

下载后解压，得到可执行文件 cdnfly-v6（或压缩包内的同名二进制），再按下文放到 plugins/cdnfly-v6/ 目录并 chmod +x。

一、插件能做什么

一次部署大致是这样：

1. 用你填写的主控地址 + API Key / Secret 连接 CDNFly
2. 上传证书一次（名称带时间戳，避免重名）
3. 按你填写的网站名称（可多个，英文逗号分隔）查找站点
4. 只改 HTTPS 监听里的证书字段，保留原有协议、套件、端口等，降低切证失败概率

适合已经在 CDNFly V6 里建好网站、只想在证书续期后自动换证的场景。

二、安装方式不同，插件目录也不同

AllinSSL 有两种常见装法，插件目录完全不一样。

很多人进了容器找不到 plugins，或在宿主机改了目录容器里却看不到，就是因为没分清这两种路径。

1. 宝塔 Docker（DK）安装

典型容器名类似：ssl-SSL-1。

要点：

• 把插件放到宿主机挂载目录，容器内才能看见。
• 只 docker cp 进容器、没有挂载的话，容器重建后会丢。
• 建议目录与二进制同名。

路径示例：

# 宿主机
/www/dk_project/dk_app/allinssl/SSL/plugins/cdnfly-v6/cdnfly-v6

# 容器内对应
/www/allinssl/plugins/cdnfly-v6/cdnfly-v6

二进制需要是 Linux amd64，并赋予可执行权限：

chmod +x /www/dk_project/dk_app/allinssl/SSL/plugins/cdnfly-v6/cdnfly-v6

若宿主机 plugins 还没挂进容器，请在 Docker 应用里把：

• 宿主机：SSL/plugins
• 映射到容器：/www/allinssl/plugins

然后重启容器。

进容器检查：

docker exec -it -w /www/allinssl ssl-SSL-1 sh
ls -la /www/allinssl/plugins/cdnfly-v6/

补充：Docker 容器里怎么唤起 AllinSSL 管理命令

容器一般是 Alpine，没有 bash。官方 allinssl.sh 写的是 #!/bin/bash，直接执行 ./allinssl.sh 常会报 no such file or directory。

请直接调二进制，并带上编号：

cd /www/allinssl
./allinssl 15   # 查看面板地址
./allinssl 3    # 重启服务
./allinssl 10   # 重启 web
./allinssl 13   # 重启后台调度

注意：无参数执行 ./allinssl 会静默退出，这是正常现象。

2. 原生 Linux 安装（非 Docker）

程序通常在 /www/allinssl/（以你实际安装目录为准）。

放置示例：

/www/allinssl/plugins/cdnfly-v6/cdnfly-v6

chmod +x /www/allinssl/plugins/cdnfly-v6/cdnfly-v6

# 可用官方脚本菜单，或直接：
cd /www/allinssl && ./allinssl 3

原生 Linux 一般有 bash，./allinssl.sh 可用；Docker 里仍优先用 ./allinssl <编号>。

3. 两种方式对照

三、插件文件怎么放（通用规范）

1. 从网盘 https://pan.ithxs.com/p/ithxs 下载并解压，得到 Linux amd64 二进制 cdnfly-v6
2. 新建目录 plugins/cdnfly-v6/
3. 把二进制放进去，文件名与目录名一致，并执行 chmod +x
4. 回到 AllinSSL 面板，工作流部署节点里应能选到 cdnfly-v6

目录结构示例：

plugins/
└── cdnfly-v6/
    ├── cdnfly-v6      # 可执行文件
    └── cdnfly.log     # 跑过之后自动生成的会话日志

若列表没有：检查架构是否 amd64、是否可执行、路径是否在程序读取的 plugins 下（Docker 还要确认挂载）。

四、在工作流里怎么配

1. 授权 / 连接配置

在 CDNFly 控制台创建 API 后填入即可。

2. 部署动作参数（deploy）

cert / key 由 AllinSSL 工作流在申请成功后自动注入，无需手填。

3. 重要：填完参数后要切到「自定义」再提交

这是 AllinSSL 主程序的问题，不是插件本身：

• 默认模式有时会把 params 存成对象
• 主程序调用插件前要求 params 是字符串
• 结果面板报：插件参数错误：params，插件进程都进不去

正确操作： 在部署节点把参数模式切到 「自定义」，确认参数以合法形式保存后再提交。

切好之后，工作流日志里应能看到「调用插件 cdnfly-v6:deploy」，而不是卡在 params 校验。

五、执行与结果怎么看

1. 面板工作流日志

成功时大致会有：

• 使用插件部署...
• 调用插件cdnfly-v6:deploy
• 插件响应 ...（主程序会 dump 返回的 status / message / result）
• 部署成功

「插件响应」那一行的前缀格式由 AllinSSL 主程序固定，插件只能尽量把 message 写清楚。

2. 插件自己的详细日志（推荐看这个）

文件在插件同目录：

# Docker 宿主机
/www/dk_project/dk_app/allinssl/SSL/plugins/cdnfly-v6/cdnfly.log

# 容器内 / 原生 Linux
/www/allinssl/plugins/cdnfly-v6/cdnfly.log

里面是分步会话日志：校验参数 → 上传证书 → 拉网站列表 → 逐站切证 → 汇总。

排错优先看这个文件。

六、常见问题

Q：Docker 里 ./allinssl.sh 没反应 / 报找不到文件？
A：容器没有 bash。用 ./allinssl 15 这类带编号的命令。

Q：宿主机放了插件，面板里没有？
A：确认 SSL/plugins 已挂载到容器 /www/allinssl/plugins；二进制为 Linux amd64 且可执行。

Q：报「插件参数错误：params」？
A：部署节点改用「自定义」模式保存参数后再跑。

Q：切证时报 https_listen / 端口无效？
A：旧逻辑可能整段覆盖监听配置。当前 cdnfly-v6 会合并原 https_listen，只改证书；请用最新二进制。

Q：网站找不到？
A：sites 填的是 CDNFly 里的网站名称，与面板列表一致；多个用英文逗号。

Q：证书名冲突？
A：默认已加时间戳后缀；也可自己填 cert_name。

七、最短操作清单

1. 从网盘下载插件：https://pan.ithxs.com/p/ithxs
2. 确认自己是 Docker 还是 原生 Linux，放到对应的 plugins/cdnfly-v6/
3. chmod +x 二进制
4. 面板工作流选 cdnfly-v6 → 填主控与 API → 填 sites
5. 参数模式切 自定义 → 保存
6. 跑一遍工作流 → 看面板是否部署成功 → 细看 cdnfly.log
7. 到 CDNFly 核对网站 HTTPS 证书是否已换成新上传的那张

按上面做完，续期流水线就可以自动把新证推到 CDNFly V6 多个站点。

小氢云网盘系统支持免费使用。部署前请先到授权站领取授权，再按本文在宝塔面板完成安装与启动。

授权地址：https://auth-v1.ithxs.com/

注册账号后进入个人中心，按页面提示获取本系统对应的授权信息（密钥稍后会在程序启动时填写）。

1. 安装宝塔面板

推荐使用宝塔面板管理服务器（进程守护、网站反代、数据库与 Redis 都更方便）。若尚未安装，请前往官网安装：

宝塔服务器面板 · 一键部署与管理

安装完成后，建议先装好：

• MySQL
• Redis
• Nginx（用于域名反代与 HTTPS，按需）

2. 上传程序文件

将安装包上传到服务器合适目录（例如 /www/wwwroot/xqy-storage），解压后可看到主程序二进制 server，以及配置文件等资源。

说明：server 即为网盘系统主程序，后续用宝塔「项目 / 进程守护」来启动它。

3. 创建数据库并确认 Redis

在宝塔中新建一个 MySQL 数据库，并记下：

• 数据库名
• 用户名
• 密码
• 主机地址（本机一般为 127.0.0.1）与端口（默认 3306）

同时确认 Redis 已安装并正常运行，记下 Redis 地址、端口与密码（若设置了密码）。

4. 修改系统配置

打开程序目录下的配置文件（常见为 config/config.yaml，若只有模板文件请先复制一份再改），重点核对两块：

1. 数据库配置：填入上一步创建的 MySQL 信息
2. Redis 配置：填入 Redis 地址、端口、密码与前缀（如有）

其余端口、站点相关项可按环境调整。若某项含义不清楚，可将配置片段发给 AI 助手对照说明后再改，避免写错导致启动失败。

5. 在宝塔创建项目（进程守护）

在宝塔中创建对应项目 / 守护进程，工作目录指向程序解压目录，启动命令指向 server 二进制（或面板提供的 Go / 通用项目启动方式）。

创建后确认：

• 进程状态为运行中
• 日志无数据库 / Redis 连接错误
• 如需外网访问，再为域名配置 Nginx 反向代理到程序监听端口

6. 填写授权，完成上线

程序启动后，按页面提示填入在授权站获取的授权密钥。填写成功即可正常使用管理后台与网盘功能。

7. 其他说明

日志切割（强烈建议开启）

长时间运行后，程序日志会持续增大。请在宝塔日志 / 进程相关设置中开启日志切割（按天或按大小），避免磁盘被日志占满。

常见排查

• 启动失败 / 端口占用：确认旧进程已停止，配置中的端口未被占用
• 连不上数据库：核对库名、账号、密码、主机与端口是否与宝塔一致
• Redis 报错：确认 Redis 已启动，密码与配置一致
• 授权失败：回到授权站核对产品与密钥是否对应本系统

按以上步骤完成后，小氢云网盘即可在服务器上稳定运行。若部署过程中遇到报错，可把日志截屏发到交流群或联系站长协助排查。

小氢云发卡系统 · 产品介绍

一、产品定位

小氢云发卡系统 是一套面向数字商品销售场景的 企业级自动发卡与多商户商城平台。

系统采用 Go 后端 + Vue 3 前端 前后端分离架构，支持 单二进制部署，前端静态资源可嵌入可执行文件，开箱即用、部署简单。适用于游戏点卡、软件激活码、会员账号、虚拟礼品、兑换券、订阅服务等 无需物流、支付即交付 的数字商品业务。

平台同时支持 平台自营 与 多商户入驻 两种运营模式：平台方可统一管理全站商品、订单、支付与商户；商户可拥有独立店铺、独立收款、独立品牌展示，在平台规则下自主经营。

典型适用场景：

• 个人或团队售卖游戏点卡、软件授权码

• 搭建数字商品自动发卡站

• 运营多商户 SaaS 型数字商品交易市场

• 需要 PC + 移动端自适应的轻量虚拟商城

二、核心价值

• 支付成功秒级自动发货，7×24 无人值守，买家下单后数秒内收到卡密或交付内容

• 卡密发卡 + URL 交付 双模式，覆盖传统卡密与 API 对接场景

• 多商户独立店铺，平台统一运维，商户独立经营

• 内置在线客服，买家悬浮聊、商户实时回，图文消息、已读状态一应俱全

• 经营数据可视化，订单趋势、收入统计、访客地理分布一屏掌握

• 多渠道支付，支付宝、微信、QQ 钱包等主流方式灵活启用

• 多套前台模板，PC / 移动端 / 通用模板可切换，支持品牌化定制

三、买家端（用户前台）功能

用户通过商城前台浏览商品、下单支付、查单取货，全程自动化。

3.1 商品浏览与选购

• 按分类浏览商品列表

• 商品详情页展示价格、库存、图文介绍、购买须知

• 支持商品搜索

• 库存显示可配置：精确数量，或「充足 / 较少 / 极少 / 售罄」等友好提示

• 首页支持轮播图、站点公告、弹窗公告

3.2 下单与支付

• 选择购买数量

• 填写联系方式（邮箱、QQ 等）

• 支持自定义下单字段（如游戏账号、备注信息等，按商品配置）

• 多种支付方式可选：支付宝、微信、QQ 钱包等

• 支持二维码扫码支付、支付跳转

• 支持支付宝订单号验证等免挂收款方式

3.3 自动交付

支付成功后，系统按商品配置自动完成交付：

卡密发卡模式：

• 从加密库存中自动出库

• 买家通过订单号或联系方式查单，即可查看卡号、卡密

• 同时展示商品使用说明

URL 交付模式：

• 支付成功后自动请求外部 HTTP 接口（GET / POST，同步 / 异步）

• 适用于对接外部系统、自动发放账号链接、激活凭证等

• 交付过程全程记录日志，便于排查

3.4 订单查询

• 凭订单号或联系方式查询订单状态

• 查看支付状态、发货状态、卡密内容

• 免费商品可自动完成全流程

3.5 在线客服

• 前台嵌入悬浮客服挂件

• WebSocket 实时聊天，无需刷新页面

• 支持文字与图片消息

• 客服在线 / 离线状态可见

• 离线时可展示提示语，并支持邮件通知客服

3.6 多商户店铺访问

• 每位商户拥有独立店铺访问地址（专属路由）

• 店铺可单独配置模板、Logo、公告、支付方式

• 买家在商户店铺内购物，商品、订单、支付、客服均与对应商户隔离

3.7 前台模板体系

系统提供多套开箱即用的前台模板，可按需切换：

• PC 端模板：适合桌面浏览器

• 移动端模板：适合手机访问，沉浸式设计

• 货源风单页模板：简洁高效

• 精品发卡模板：独立布局风格

• uniapp 风格模板：跨端体验

• 现代化 UI 模板：视觉更现代

系统会根据访问设备自动选择 PC 或移动模板，也支持手动指定。

四、平台管理后台功能

平台管理员通过 Web 管理后台，掌控全站运营。

4.1 数据仪表盘

• 总销售额、今日销售额、成本、利润

• 订单总数、今日订单、待处理订单

• 在售商品数、低库存预警

• 销售趋势图表（按日 / 按周）

• 支付方式分布（成交额占比）

• 热销商品排行榜

• 访问地理分布大屏（全球视图 / 全国视图）

• 官方公告与广告位展示

4.2 商品与分类管理

• 分类管理：增删改查、排序、启用 / 禁用

• 商品管理：

  • 价格、成本、库存、排序

  • 富文本商品详情、使用说明

  • 自定义下单字段配置

  • 交付方式选择（卡密 / URL）

  • URL 交付规则配置（请求地址、方法、参数、成功判断条件）

  • 商品启用 / 禁用、上下架

4.3 订单管理

• 订单列表：按状态、时间、商品等筛选

• 订单详情：买家信息、支付信息、交付内容

• 手动标记支付、手动补发卡密

• 取消订单、批量删除

• 订单流程日志：状态变更全链路追踪（待支付 → 已支付 → 已发卡 → 已取消）

4.4 卡密管理

• 卡号、卡密 AES-256 加密存储，安全可靠

• 单条录入、批量导入、批量删除

• 与商品库存联动，发卡后自动扣减

• 卡密绑定订单，防止重复发放

4.5 支付配置

支持多种支付通道类型：

• 易支付 V1 / V2：聚合支付对接

• 支付宝备注转账：好友转账 / 备注收款

• 支付宝订单号验证：免挂收款验证

各通道可独立启用支付宝、微信、QQ 支付开关，满足多样化收款需求。支付异步回调与同步跳转分离，确保订单状态准确。

4.6 多商户管理（平台拓展能力）

• 商户列表：开通 / 禁用、到期时间管理、余额调整、密码重置

• 商户详情：商品、分类、订单、操作日志一站式查看

• 商品审核：可配置商户商品是否需平台审核后上架

• 套餐管理：月租 / 季租 / 年租 / 永久等套餐 CRUD

• 商户公告：面向商户的官方通知发布

• 多商户经营仪表盘：商户维度数据概览

4.7 系统配置

• 网站配置：站点标题、名称、SEO 关键词与描述、Logo、Favicon、首页公告、弹窗公告、轮播图

• 订单号规则：前缀、时间戳、日期随机、日期序号、纯随机等多种生成方式

• 模板管理：PC / 移动 / 通用模板在线切换，支持模板可配置项

• 域名管理：多域名绑定、启用 / 禁用、访问控制

• 邮箱配置：多 SMTP 账号、连接测试、发信测试

• 节点管理：云端授权节点切换、连接测试

• 验证码配置：数字 / 字母 / 极验人机验证

4.8 在线客服工作台

• WebSocket 实时会话列表

• 与买家实时文字、图片聊天

• 消息已读标记、会话关闭

• 客服图片管理与过期清理

4.9 日志中心

• 管理员登录日志

• 访问日志（IP、路径、地理位置、耗时）

• 操作日志（管理员行为记录）

• 邮件发送日志

• URL 交付请求日志

• 产品版本更新日志

4.10 系统工具

• 在线升级：版本检测、程序热更新、服务重启

• 接口文档：内置前台公共 API 文档在线查看

• 服务器监控：WebSocket 实时查看 CPU、内存、磁盘等资源

• 演示站模式：定时重置业务数据，适合演示环境

• 守护进程：程序意外退出自动重启

五、商户后台功能

每位入驻商户拥有独立后台，完成从开店到收款的完整经营闭环。

5.1 经营总览（仪表盘）

• 账户余额、今日交易额、今日利润、今日订单数

• 在售商品数、库存不足提醒、待处理订单

• 账户到期状态提醒（已到期 / 即将到期 / 正常）

• 销售趋势分析（近 7 天 / 近 30 天）

• 支付方式分布、订单状态分布

• 热销商品排行榜（按成交额）

5.2 访问数据分析

• 地理分布大屏：全球 / 全国视图一键切换

• 时间范围：24 小时 / 7 天 / 30 天 / 全部

• 总访问量、国家数、省份数统计

• 国家 / 省份访问排行榜

• 访问日志：按 IP、路径、时间筛选，查看详细访问记录

• WebSocket 实时推送：访问事件、统计数据实时更新

5.3 店铺管理

• 独立店铺路由：绑定 / 更换专属访问地址

• 模板选择：通用 / PC / 移动端模板

• 品牌与 SEO：站点标题、关键词、描述、Logo、Favicon

• 公告管理：站点公告、弹窗公告（富文本）

• 在线客服配置：开关、欢迎语、离线提示、离线邮件通知

5.4 商品与订单

• 商品创建、编辑、删除、排序

• 平台开启审核时，新建 / 变更商品进入待审状态

• 自建商品分类体系

• 卡密库存：单条录入、批量导入、批量删除

• 订单列表与详情查询

• URL 交付 API 调用日志

• 操作记录留痕

5.5 支付与财务

• 收款配置：自有支付通道增删改、启用 / 停用

• 余额充值：发起充值、查看充值记录、在线支付

• 套餐订阅：查看 / 购买套餐、自动续费开关、订阅记录

• 到期邮件提醒（7 / 3 / 1 天可配置）

5.6 公告中心

• 查看平台发布的官方公告

• 公告详情阅读、阅读次数统计

5.7 客服工作台

• 与买家实时聊天（文字 + 图片）

• 会话管理、在线状态设置

5.8 账号与安全

• 个人资料维护、修改密码

• 邮箱验证码绑定 / 解绑

• 聚合登录：QQ / 微信 / 支付宝 OAuth 绑定与快捷登录

六、支付与订单能力详解

6.1 订单生命周期

买家下单 → 待支付 → 支付成功 → 自动发货 / 手动补发 → 已交付

↓

取消订单

• 支持免费商品自动完成

• 支付异步回调 + 同步跳转双保险

• 下单成功、发卡成功均可触发邮件通知

6.2 支付通道

平台与商户各自维护支付通道，互不干扰。

6.3 卡密安全

• 卡号、卡密 AES-256 加密存储

• 密钥基于系统 JWT 密钥派生，即使数据库泄露也难以解密

• 发卡后绑定订单，防止重复出库

七、在线客服体系

三端 WebSocket 实时通信，售前售后沟通顺畅：

• 欢迎语、离线提示可配置

• 客服离线时自动邮件通知

• 图片消息带过期时间，定时清理节省空间

• 消息已读状态可见

八、适用场景

场景一：游戏点卡 & 激活码（高频场景）

批量导入卡密、自动出库、库存预警，支持多规格 SKU，支付成功秒级自动发货，7×24 无人值守。

场景二：会员 & 订阅服务

对接 URL 交付或 API 回调，支付成功后自动发放账号、链接或凭证，减少人工客服成本。

场景三：虚拟礼品 & 兑换券

支持限时链接、一次性卡密，适合活动促销、渠道分销，订单与交付全程可追溯。

场景四：多商户 SaaS 平台

为平台方提供商户入驻、独立店铺、统一支付与运维能力，快速搭建数字商品交易市场。

九、接入流程（三步上线）

1. 注册并配置店铺 — 填写基本信息，设置店铺名称、支付渠道与商品分类

2. 上架商品与库存 — 导入卡密或配置 URL 交付规则，设置价格、库存与购买须知

3. 分享链接自动成交 — 买家下单支付后系统自动发货，订单与交付记录后台实时可查

十、技术架构与亮点

10.1 部署形态

• 单二进制部署：Go 后端 + 前端静态资源 embed，一个文件即可运行

• 也支持将前台模板放到外部目录，热切换无需重新编译

• 守护进程：崩溃自动重启，保障服务可用性

10.2 技术栈

• 后端：Go + Gin + MySQL + Redis + JWT + WebSocket

• 平台管理后台：Vue 3 + Vben Admin 5 + Ant Design Vue

• 商户后台：Vue 3 + Vben Admin 5（独立应用 + 平台内嵌双入口）

• 产品官网：Vue 3 + Vben Admin 5

• 用户前台：Vue 3 + Vant / Ant Design Vue / Tailwind / wot-ui 等多套模板

10.3 性能与安全

• Redis 缓存：站点配置、商品、分类、商户店铺等热点数据

• 限流中间件、CORS、请求 ID 追踪

• JWT 认证（管理员 / 商户分离）

• 卡密 AES 加密、密码加盐哈希

• 演示站写保护

• IP 地理位置解析，支撑访问统计大屏

10.4 运维能力

• 在线升级：检测新版本、上传更新包、热重启

• 自动建表 / 补字段：重启即完成数据库迁移

• Gzip 压缩、静态资源浏览器缓存

• 内置 API 文档

十一、产品官网

系统内置独立产品官网模块，包含：

• 产品介绍首页（Hero、数据统计、支付通道、功能卡片、使用场景、接入流程、客户反馈、FAQ）

• 商户注册页（邮箱验证码注册、人机验证）

• 支持自定义访问前缀，可独立域名部署

https://auth-v1.ithxs.com/#/backend/profile

先生成RSA签名

在你的商城后台设置里有这两个配置项，把刚才生成的填进去就行了

前提是，生成这个密钥的这个平台用户要和你的授权关联，就是说授权必须是这个用户关联的才可以！

小氢云商城系统 — 产品介绍

一句话定位

小氢云商城系统是一款面向虚拟商品 / 数字商品经营者的全链路 SaaS 电商平台：以自动发卡、货源对接、订单自动化为核心，覆盖 PC 商城、H5 移动端、用户中心、管理后台，并集成虚拟主机、分站分销、第三方电商对接与 AI 运营能力。

让虚拟商品生意：上架快、发货快、对接快、运营快。

一、产品定位

小氢云商城系统是一款面向数字商品（虚拟商品）商家的全功能自动化电商平台。系统以自动发卡为核心，上游对接多家货源供应商实现订单自动处理、卡密自动返回；下游提供 PC 商城 + PE（H5）+ 管理后台 + 用户中心 的全链路解决方案。

适用于：自动发卡商家、数字商品分销平台、虚拟主机服务商、多渠道电商货源整合平台。

二、我们解决什么问题

三、核心架构

技术栈

• 后端: Go + Gin 框架 + MySQL + Redis
• 管理后台: Vue 3 + Vite + Ant Design Vue 4
• 用户中心: Vue 3 + Ant Design Vue 4
• PC 商城: Vue 3 + Ant Design Vue 4 + Element Plus
• PE 移动端（H5）: UniApp 构建 Web 产物，嵌入 Go 后端供手机浏览器访问
• 部署: 前后端分离，前端构建产物嵌入 Go 二进制，单文件部署

多端覆盖

                    ┌─────────────────────────────────┐
                    │     Go 后端（Gin + MySQL + Redis）│
                    │  订单 · 支付 · 货源 · 插件 · AI   │
                    └───────────────┬─────────────────┘
                                    │
        ┌───────────┬───────────┬───┴───┬───────────┬───────────┐
        ▼           ▼           ▼       ▼           ▼           ▼
    管理后台      用户中心      PC商城   PE(H5)    模板装修SSR   Android客服
    (admin)       (user)        (pc)               (可视化建站)   (员工端)

四、功能全景

4.1 商城前台（消费者端 · PC + PE H5）

商品浏览与购买

• 多级分类导航、商品搜索
• 商品详情（富文本描述 + 自定义输入框 + 多级价格）
• 会员等级差价、密价隐藏、限购策略
• 购物车合并下单、批量下单
• 砍价活动：发起砍价、分享好友帮砍、动态追踪
• 秒杀活动：限时抢购、倒计时、库存管理
• 免费商品：零元购引流
• 优惠券：领取、核销、满减
• 幸运抽奖：大转盘抽奖、实物奖品发货

订单与支付

• 多种支付方式：余额支付、支付宝/微信在线支付、活动余额、独立支付接口、余额卡密充值
• 余额充值（在线支付 + 卡密充值）
• 余额转账、余额提现（审核流程）
• 订单实时进度追踪 + 操作日志
• 售后申请 + 在线客服聊天
• 游客下单 + 查单密码验证

用户中心

• 个人仪表盘（资产总览、订单概览）
• 邮箱/手机号绑定（含极验滑块验证码）
• 实名认证：三要素认证（姓名+身份证+手机号），对接阿里云市场
• 收货地址管理
• 邀请管理 + 下级用户追踪 + 邀请佣金
• 等级升级、消费任务、操作日志
• 系统对接 / API 密钥管理
• 快捷登录绑定（QQ/微信/支付宝等）
• 每日签到

4.2 自动发卡与货源生态

商品侧

• 17 种下单输入框类型（账号、邮箱、SKU、主机配置、图片/KYC 上传等）
• 多级分类、梯度价、会员等级价、密价、限购、历史价
• 本地卡密库存 + 上游货源混合售卖
• 商品审核流（供货商提交 → 管理员审核）

已对接 / 可对接货源

另支持 provider.* 货源插件，JS 钩子扩展任意上游 API。

自动化运维（计划任务） 商品库存监控、价格监控、订单同步、自动上下架、货源余量告警、自动确认收货、余额监控告警、实名认证余量监控、数据库定时备份等。

4.3 模板装修：不写代码改前台

模板装修（new） 是独立的可视化建站系统：

• 158+ 业务组件，另支持 Wot / Vant / Ant Design 皮肤库
• 手机 / 平板 / 桌面三端独立布局，同一 type 协议自适应
• Go SSR 整页输出，SEO 友好，按钮/表单可真实交互
• AI 装修助手：自然语言驱动页面搭建
• 与旧版「网站装修」独立，数据存 sky_template_decoration

适合：品牌站、活动页、分站首页、差异化落地页。

4.4 虚拟主机系统

集成轻量级虚拟主机管理功能，支持：

• 主机生命周期：开通、续费、升级、扩容、到期监控
• 在线文件管理（新建/编辑/上传/解压/权限设置）
• PHP 版本切换、运行目录设置
• 自定义域名绑定 + SSL 证书管理
• URL 重定向 / 伪静态配置
• 数据库管理（在线 SQL 执行）
• 内置应用商店（一键部署 Go 应用）
• 访问日志 / 错误日志、服务器资源监控
• 多服务器管理、宝塔 API 对接

4.5 分站（多租户）系统

支持子站点独立运营，每个分站拥有：

• 独立域名绑定 + HTTPS
• 独立支付接口配置
• 独立商品展示（可覆盖主站价格、自定义上下架）
• 独立分类体系、独立会员等级定价
• 子账号管理、收益统计、分站模板/主题切换

4.6 电商平台对接

闲管家（闲鱼/鱼市场）

• 多账号管理、店铺绑定
• 商品同步（发布/下架/编辑）
• 订单同步 + 自动/手动发货
• 卡密与兑换链接回传
• 商品价格/库存变更订阅

阿奇索（91卡券）

• 与闲管家对标的功能矩阵
• 直充下单 + 卡密下单双模式

4.7 AI 能力

客服关键词库与 AI 回复可共用，人工规则优先，大模型兜底。

4.8 在线客服

• WebSocket 实时聊天（PC/PE H5 前台 + 管理端）
• 快捷回复、分组管理、关键词自动回复
• 售后工单联动
• Android 员工端 App：移动端接待、消息推送、快捷回复管理

4.9 插件与应用商店

插件钩子系统（21 个钩子分组）让第三方开发者在不改 Go 核心的前提下扩展：

• 订单事件（支付成功、改价、自定义展示）
• 自定义支付渠道（payment.*）
• 货源插件（provider.* 十一钩子）
• 附件上传、设置面板、Action 多端路由
• AES 加密分发 + 授权绑定，防拷贝

4.10 管理后台（运营端）

商品管理

• 商品全生命周期管理（创建/编辑/复制/删除/批量操作）
• 多级分类树 + 批量分类导入
• 货源对接管理（上游供应商 CRUD）
• 商品审核流程（供货商提交 → 管理员审核）
• 兑换卡密生成管理、商品卡密批量导入/导出
• 密价管理、限购配置、历史价显示、批量调价
• 商品操作日志全追踪

订单管理

• 订单列表（高级搜索/筛选/排序/导出）
• 订单详情 + 进度日志 + 回调日志
• 手动补单、修改状态、更新备注
• 售后管理（列表/统计/设置）
• 客服系统（在线聊天/快捷回复/关键词自动回复）

供货商管理

• 供货商入驻申请审核
• 供货商列表 / 商品审核 / 订单查看
• 供货商资料审核、结算与佣金
• 强制实名拦截（未实名无法上架商品）

用户管理

• 用户列表 + 编辑 + 余额调整 + 等级调整
• 用户权限管理 + API 权限
• 实名认证记录 + 超管解密
• 余额操作日志 + 提现审核
• 余额卡密管理（生成/发放/核销）

活动营销

• 优惠券（创建/发放/核销/补贴/回收）
• 秒杀活动（定时上下架）
• 砍价配置（每商品独立规则）
• 幸运抽奖（多活动多奖品 + 实物发货）

支付与财务

• 支付接口管理（支付宝/微信/易支付等）
• 支付方式配置与展示控制
• 充值记录 / 支付回调日志

系统配置

• 网站基础设置（标题/注册开关/登录控制等）
• 安全配置（密码盐/JWT/操作密钥/IP黑名单）
• OAuth 聚合登录配置
• 短信服务商（腾讯云 SMS）、邮件服务（SMTP）
• 云存储（阿里云 OSS / 腾讯 COS / 七牛）
• 数据库备份/恢复/迁移
• 系统任务调度、服务器性能监控
• API 请求日志 / 操作日志
• 缓存管理（Redis 一键清理）、敏感词过滤

员工与权限

• 多角色管理（管理员/员工/供货商）
• 员工账户 CRUD、API 粒度权限分配、菜单级权限控制

素材管理

• 图片/视频分组上传、素材库统计

五、系统亮点

1. 全自动化发卡：用户下单 → 自动调上游 → 自动返回卡密，全程无人值守
2. 多渠道货源整合：一个平台对接多家上游供应商，自动比价/切换
3. 双端商城 + 全后台：PC 商城 + PE（H5）+ 管理后台 + 用户中心，一套系统全搞定
4. 可扩展插件生态：支付/通知/货源均可插件化，不写核心也能接新渠道
5. 可视化 SSR 建站：模板装修 + AI 助手，品牌站不用另找 CMS
6. 虚拟主机集成：自带轻量级主机管理面板，不依赖第三方
7. 电商平台对接：直接对接闲鱼/闲管家/91卡券，拓展销售渠道
8. 分站（多租户）：一个主站可开无数个子站，独立运营独立结算
9. 供货商模式：支持供货商入驻、自主上架、管理员审核，平台化运营
10. AI 加持：商品讲解、QQ 购物流、迁库助手，降低人力成本
11. 高性能 Go 后端：单文件部署、协程并发、Redis 缓存、资源占用极低
12. 丰富营销工具：砍价/秒杀/优惠券/抽奖/签到/密价，提升转化

六、适用场景

七、目标用户

小氢云商城系统 — 让虚拟商品生意更简单

1、确定你的需求

比如你想做一个清理清理某个表数据的插件，就拿接口日志举例。

接口日志的表叫 sky_log，这个可以问 AI 助理。

你可以给 AI 助理说：我想做一个清理 sky_log 表数据的插件，可以选择日期区间清理，要有二次确认对话框，要有数据统计和分组展示日志类型，支持选择分组进行清理！UI 要兼容手机端和电脑端

回车发送等 Ai 处理即可

2、开发过程

已经在自动创建对应插件文件了

3、看看效果

二次确认也有

成功被删除了，后续有任何需求都可以给 AI 助理讲，让他给你开发！！！

后续拓展

你可以把插件下载下来然后去授权站开通开发者账号上传插件赚钱

把插件下载下来，然后去 https://auth-v1.ithxs.com 申请开通开发者账号就可以上架插件啦！

本文面向「已拿到 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

自定义工作流完全指南：从零到一键部署

本文档级别：嚼碎了喂嘴里。假设你从未写过脚本，按顺序读、按顺序做，就能写出和系统内置「一键部署小氢云脚本」同等级的自动化流水线。

目录

1. 30 秒搞懂：这到底是什么
2. 管理端：第一次打开编辑器（逐步点击）
3. 脚本运行的底层机制（知道这些就不踩坑）
4. 命名与参数：一张表记牢
5. host_id 与 host_source：最容易搞混的点
6. 第一个能跑的脚本（逐行解释）
7. 内置节点返回值对照表（必收藏）
8. 日志工具：直接复制粘贴
9. 通用工具函数：示例脚本逐函数讲解
10. 与用户弹窗交互：request_user_input 全解
11. 八步部署流水线：每一步干什么、为什么、怎么写
12. Go 项目查重：为什么不用 get_go_project_detail
13. 启动失败自动重建：容错逻辑
14. 邮件通知模板
15. 自定义节点：从创建到在工作流里调用
16. 发布、上架、挂到用户主机
17. 执行结果面板：怎么看日志
18. 故障排查矩阵
19. 完整配置区 + 最小可运行模板
20. 附录：常用内置节点速查

1. 30 秒搞懂：这到底是什么

一句话： 在管理后台写一段 JavaScript，里面调用一个个「节点函数」（如上传文件、建数据库），系统自动在宝塔面板上帮你执行。

三个角色：

执行时发生什么：

1. 你点「运行」或用户在主机详情点快捷按钮
2. 服务端用 Goja 引擎跑你的 JS
3. 每调用一次 xxx({...})，记为一步，结果推送到前端
4. console.log 的内容出现在「控制台日志」
5. 某步失败 → 立刻中断，后面不再跑（除非你自己用 if 吃掉错误）

2. 管理端：第一次打开编辑器（逐步点击）

2.1 进入路径

左侧菜单 → 工作流管理 → 右上角「新建工作流」 或直接访问：/workflow/editor

2.2 界面分区（从左到右）

2.3 第一次运行（逐步）

1. 名称填：测试检查文件
2. 中间编辑器全选删除，粘贴 第 6 节 的代码
3. 顶部 执行主机 ID 填一个真实主机 ID（在主机列表可查）
4. 点 运行（无需先保存，会直接跑编辑器里的内容）
5. 弹出 执行结果 抽屉：
   • 上方：成功/失败
   • 步骤明细：每一步调了哪个函数、参数、返回值
   • 控制台日志：console.log 输出

2.4 保存与发布

调试技巧： 改脚本 → 直接点运行 → 看日志 → 改完再点保存。不必每次保存。

3. 脚本运行的底层机制

3.1 脚本被包在 IIFE 里

系统自动把你的脚本包成：

(function(){
  // 你的脚本
})();

所以你可以在最外层用普通语句，不要用 return 退出（除非配合 end_workflow）。

3.2 host_id 自动注入

当你在编辑器填了「执行主机 ID」，或用户在用户中心对某台主机跑工作流，系统会在脚本最开头插入：

var host_id = 123;
var hostId = 123;
// 然后才是你的脚本

并且会删掉你脚本里原有的 const/let/var host_id = ... 和 hostId = ... 赋值行，避免冲突。

3.3 节点调用 = 一步操作

var r = check_file_exists({ host_source: "auto", dirPath: "/", fileName: "a.txt" });

等价于：校验参数 → 调后端 → 宝塔查文件 → 把结果塞回 r。

失败时： 抛异常，脚本中断，执行结果标记失败。

成功时： 返回对象；若节点没定义特殊字段，自动补 status: true, code: 200。

3.4 暂停与续跑（request_user_input）

调用 request_user_input 时：

1. 后端保存当前已完成的步骤快照
2. 向前端推送「等待输入」
3. 用户填完点确定 → 调用 resume 接口 → 从断点继续，已完成步骤不会重复执行

用户点取消 → 返回 { cancelled: true }，由你决定是 end_workflow 还是 throw。

3.5 超时

整段脚本最长 5 分钟。单步超时看各节点配置（自定义节点默认 30 秒）。

4. 命名与参数：一张表记牢

铁律： 参数对象里的键名必须和操作参考里一致，写错键 = 参数传不进去。

5. host_id 与 host_source

5.1 两种 host_source

5.2 auto 模式下路径怎么拼

设当前主机名为 shop.example.com，站点根目录固定为：

/www/wwwroot/shop.example.com

此时：

check_file_exists({
  host_source: "auto",
  dirPath: "/",              // → /www/wwwroot/shop.example.com
  fileName: "index.php"
});

check_file_exists({
  host_source: "auto",
  dirPath: "public/uploads", // → /www/wwwroot/shop.example.com/public/uploads
  fileName: "logo.png"
});

5.3 custom 模式

check_file_exists({
  host_source: "custom",
  host_id: hostId,           // 数字或变量
  dirPath: "/www/wwwroot/shop.example.com",
  fileName: "index.php"
});

5.4 本地文件 upload 路径（与 host 无关）

上传前： 把 zip 放到 doc 目录，否则报「本地文件不存在」。

6. 第一个能跑的脚本

复制下面整段 → 粘贴到编辑器 → 填执行主机 ID → 运行。

// ===== 第 1 步：检查站点根目录有没有 index.php =====
var result = check_file_exists({
  host_source: "auto",
  dirPath: "/",
  fileName: "index.php"
});

// ===== 第 2 步：打印结果（在「控制台日志」里看）=====
console.log("API 是否成功:", result.status);
console.log("文件是否存在:", result.found);   // 注意：字段名是 found，不是 exists

// ===== 第 3 步：根据结果分支 =====
if (result.found) {
  console.log("index.php 已存在，无需处理");
} else {
  console.log("index.php 不存在，可以在这里继续 upload_file 或 create_file");
}

逐行解释：

• check_file_exists：节点函数，查远程目录里有没有某文件
• host_source: "auto"：用当前主机，不用手写路径里的主机名
• dirPath: "/"：站点根目录（不是服务器根 /）
• fileName：只写文件名，不含路径
• result.found：true=找到，false=没找到（没找到不算 API 失败）
• result.status：API 调用本身是否成功

7. 内置节点返回值对照表

写 if 判断前先看这张表，不同节点字段名不一样。

7.1 通用成功

大多数写操作（create、delete、unzip…）成功时：

{ "status": true, "code": 200 }

7.2 check_file_exists

if (result.found) { /* 存在 */ }
if (!result.found) { /* 不存在，但 API 可能仍 status=true */ }

7.3 database_exists

// 必须用 value，不要直接用 status 判断库是否存在
function isDatabaseExists(r) {
  return !!(r && r.value === true);
}

7.4 upload_file

执行过程中前端可通过 WebSocket 看实时上传进度。

7.5 port_rule_exists

7.6 get_go_project_detail

注意： 部署脚本故意不用此节点做查重，见 第 12 节。

7.7 start_go_project

失败时不抛错，返回 { status: false, code: 404, error: "..." }，需自己判断。

7.8 request_user_input

7.9 bind_user_domains_local

7.9 replace_config_content

8. 日志工具

直接复制到脚本顶部，和示例脚本保持一致：

var logSequence = 0;

function padLogIndex(value) {
  return value < 10 ? "0" + value : String(value);
}

// 主步骤：[01] [02] … 自动递增
function logInfo(message) {
  logSequence += 1;
  console.log("[" + padLogIndex(logSequence) + "] " + message);
}

// 子步骤：树形缩进，不占主序号
function logDetail(message) {
  console.log("         └─ " + message);
}

// 阶段标题：固定 01~08，和流程图对齐
function logPhase(phaseNo, title) {
  console.log("[" + padLogIndex(phaseNo) + "] " + title);
}

输出效果：

[01] 初始化部署上下文 [01] 主机: demo.com | 用户: zhangsan └─ siteRootPath: /www/wwwroot/demo.com [02] 检测并上传部署包 [03] 远程包已存在，跳过上传

9. 通用工具函数

以下全部来自 一键部署小氢云脚本.js，建议原样复制。

9.1 sanitizeGoProjectName / sanitizeDbName

宝塔 Go 项目名、MySQL 库名不能含 . 和 -：

function sanitizeGoProjectName(hostName) {
  return String(hostName || "").replace(/\./g, "_").replace(/-/g, "_");
}
// shop.example.com → shop_example_com

数据库名规则相同，用 sanitizeDbName。

9.2 randomDbPassword

新建库且主机记录无密码时，生成 16 位随机密码（去掉易混淆字符 0/O/1/l/I）。

9.3 normalizeDomainInput

用户可能输入 https://shop.com/ 或 shop.com/path，统一成 shop.com：

• 去首尾空格、末尾 /
• 去 http:// / https://
• 去路径部分

9.4 assertActionSuccess

function assertActionSuccess(actionResult, actionName) {
  if (!actionResult || actionResult.status !== true) {
    throw new Error(actionName + " 失败: " + JSON.stringify(actionResult || { status: false }));
  }
  return actionResult;
}

用于 create_database、replace_config_content 等必须成功的步骤。

9.5 isDatabaseExists

function isDatabaseExists(checkResult) {
  return !!(checkResult && checkResult.value === true);
}

10. 与用户弹窗交互

10.1 全部 input_type

10.2 示例脚本里的域名选择（完整逻辑）

function requestBindDomain(hostInfo) {
  var boundDomains = parseBoundDomains(hostInfo);

  // SSL 开了就用 https
  var enableHttps = hostInfo && (
    hostInfo.ssl_enabled === 1 || hostInfo.ssl_enabled === true ||
    hostInfo.ssl_force_https === 1 || hostInfo.ssl_force_https === true
  );
  var urlScheme = enableHttps ? "https" : "http";

  // 已有域名做成下拉选项
  var domainOptions = [];
  for (var i = 0; i < boundDomains.length; i++) {
    domainOptions.push({ label: boundDomains[i], value: boundDomains[i] });
  }

  var inputResult = request_user_input({
    title: "绑定域名",
    content: boundDomains.length ? "请选择或输入域名" : "请输入要绑定的域名",
    input_type: "combobox",
    placeholder: "example.com",
    options: domainOptions,
    required: true,
    field_key: "domain"
  });

  if (inputResult.cancelled) {
    end_workflow({ message: "用户取消了域名输入" });  // 成功结束，不算失败
  }

  var selectedDomain = normalizeDomainInput(inputResult.value);
  if (!selectedDomain) throw new Error("域名不能为空");

  return {
    bindDomain: selectedDomain,
    appBaseUrl: urlScheme + "://" + selectedDomain
  };
}

10.3 parseBoundDomains

hostInfo.domains 可能是 JSON 字符串、数组或逗号分隔文本——此函数统一解析成字符串数组。

11. 八步部署流水线

下面按 [01]~[08] 逐步说明：做什么、判断条件、关键代码。

[01] 初始化部署上下文

干什么：

1. get_host_info 拿主机名、端口、数据库信息、domains
2. get_user_info 拿用户名、邮箱（后面发邮件）
3. requestBindDomain 弹窗选域名 → 得到 appBaseUrl
4. 算出所有路径变量

派生变量（记住公式）：

var siteRootPath = "/www/wwwroot/" + hostInfo.host_name;
var remotePackagePath = siteRootPath + "/" + packageFileName;
var binaryFilePath = siteRootPath + "/" + binaryFileName;
var configFilePath = siteRootPath + "/config/config.yaml";
var goProjectName = sanitizeGoProjectName(hostInfo.host_name);
var servicePort = (hostInfo.port && hostInfo.port > 0) ? hostInfo.port : defaultPort;

[02] 检测并上传部署包

流程图：

check_file_exists(zip) ├─ found=true → 跳过上传 └─ found=false → upload_file → 再 check 一次校验

上传代码：

uploadResult = upload_file({
  host_source: "custom",
  host_id: hostId,
  targetDir: siteRootPath,
  fileName: packageFileName,
  content_source: "local",
  content: localPackagePath   // 如 @/jjwk-service-v2.4.8-install.zip
});

必须检查： uploadResult.status === true && uploadResult.progress === 100

[03] 解压并校验二进制

何时解压：

var shouldExtractPackage = !binaryExistsResult.found || (packageUploaded && forceUnzipAfterUpload);

解压后：check_file_exists 确认二进制存在 → set_file_access 设为 www:755。

[04] 检查并初始化数据库

database_exists(dbName) ├─ value=true → 跳过创建，从 hostInfo 读 db_name/db_account/db_password └─ value=false → create_database → 再 database_exists 校验

库名默认 sanitizeDbName(host_name)。无密码则 randomDbPassword(16)。

[05] 更新 config.yaml

replace_config_content({
  format: "yaml",
  host_id: hostId,
  filePath: configFilePath,
  replacements: {
    "database.host": "127.0.0.1",
    "database.port": "3306",
    "database.username": databaseUser,
    "database.dbname": databaseName,
    "database.password": databasePassword,
    "app.base_url": appBaseUrl,
    "app.port": servicePort
  }
});

注意： 键必须是 yaml 里的点分路径；任一键在文件里不存在 → 整步失败。

[06] 检查并放行端口

port_rule_exists(port) ├─ exists=true → 跳过 └─ exists=false → set_port_rule → delay(2秒)

create_go_project 里可设 release_firewall: true，但示例脚本在 [06] 单独做，且创建项目时设 release_firewall: false 避免重复。

[07] 注册并启动 Go 项目

见 第 12、13 节。

[08] 发送部署完成通知

有邮箱则 send_email（异步，不阻塞）；无邮箱打日志跳过。

12. Go 项目查重

为什么不用 get_go_project_detail？
实测易误判「不存在」，导致跳过 create_go_project，后面 start_go_project 又失败。

正确做法： 只用 get_go_project_list，封装 findGoProject：

1. 用项目名、主机名、sanitize 后的主机名分别搜索
2. 每条列表项用三种规则匹配：路径相同 / 项目名相同 / 主机名相同
3. 搜不到再全量拉 1000 条扫描

创建后用 verifyGoProjectExists：最多重试 5 次，每次间隔 2 秒，等宝塔列表刷出来。

13. 启动失败自动重建

var startGoProjectResult = start_go_project({ projectName: activeProjectName });

if (!startGoProjectResult || startGoProjectResult.status !== true) {
  // 启动失败 → 重新 create_go_project → verify → 再 start
  create_go_project({ /* 同参数 */ });
  verifyGoProjectExists(...);
  startGoProjectResult = start_go_project({ projectName: activeProjectName });
}
assertActionSuccess(startGoProjectResult, "start_go_project");

另外： bind_user_domains_local 在启动前执行，把域名写入本系统主机记录（与宝塔绑定独立）。

14. 邮件通知模板

send_email({
  to: userProfile.email,
  subject: "主机搭建通知 - " + hostInfo.host_name,
  body: "<p>主机 <strong>" + hostInfo.host_name + "</strong> 工作流执行完成。</p>" +
    "<ul>" +
    "<li>部署包: " + (packageExistsResult.found ? "已存在（跳过上传）" : "已上传") + "</li>" +
    "<li>二进制: " + (/* 是否重新解压 */) + "</li>" +
    "<li>数据库: " + databaseName + (databaseCreated ? "（新建）" : "（已存在）") + "</li>" +
    "<li>站点域名: " + bindDomain + "（" + appBaseUrl + "）</li>" +
    "<li>Go 项目: " + activeProjectName + "（端口 " + servicePort + "）</li>" +
    "</ul>"
});

send_email 提交后立即继续，不等发信结果。

15. 自定义节点

路径：自定义节点 → 新建

15.1 必填项

15.2 脚本内置对象

// ctx.params     — 调用方传入的参数
// ctx.host_id    — 主机 ID
// ctx.base_url   — 有 host_id 时为宝塔面板地址，否则管理端地址
// ctx.api_path   — 节点配置的默认路径
// ctx.api_method — 默认 HTTP 方法
// ctx.admin_token / ctx.user_token — 按场景注入

15.3 request / handle_response 模板

var resp = request({
  url: ctx.api_path,
  method: ctx.api_method || "POST",
  headers: { "Content-Type": "application/json" },
  body: ctx.params,
  timeout: ctx.timeout_sec || 30
});

return handle_response(resp, function(json) {
  if (json.http_status >= 400) {
    return { status: false, code: json.http_status, message: json.msg || "HTTP 失败" };
  }
  if (json.code !== undefined && json.code !== 200) {
    return { status: false, code: json.code, message: json.msg || "业务失败" };
  }
  return { status: true, code: 200, data: json.data !== undefined ? json.data : json };
});

15.4 在工作流里调用

var r = sync_user_quota({ host_id: hostId, quota_mb: 1024 });
if (!r.status) throw new Error("同步失败");

启用节点后，左侧操作参考会出现该函数。

16. 发布、上架、挂到用户主机

导入导出： 列表页可导出 JSON（含 script），换环境导入。

17. 执行结果面板

步骤为空？说明脚本里没调用任何节点函数（纯 console.log 不会出现步骤）。

18. 故障排查矩阵

19. 完整配置区 + 最小可运行模板

19.1 配置区（改这里就够）

const hostId = "";                                          // 或靠编辑器注入
const localPackagePath = "@/your-app-install.zip";
const packageFileName = "your-app-install.zip";
const binaryFileName = "your-app";
const defaultPort = 9001;
const forceUnzipAfterUpload = true;

19.2 幂等设计检查清单

• 上传前 check_file_exists
• 上传后再 check 一次
• 解压前判断二进制 + force 标志
• 建库前 database_exists
• 建库后再 exists 校验
• 端口 port_rule_exists
• Go 项目 findGoProject 查重
• 创建后 verifyGoProjectExists
• 启动失败 recreate 分支

19.3 建议学习顺序

1. 跑通 第 6 节 检查文件
2. 加 upload_file 上传一个小 txt
3. 加 request_user_input 弹窗
4. 复制完整示例脚本，只改配置区
5. 对用户主机上架测试

20. 附录：常用内置节点速查

文件

get_dir_new create_dir create_file delete_file get_file_body save_file_body move_file zip_files unzip_files set_file_access upload_file check_file_exists replace_config_content

数据库

create_database database_exists delete_database get_database_info

Go 项目

get_go_project_list get_go_project_detail create_go_project start_go_project stop_go_project delete_go_project add_go_project_domain modify_go_project

防火墙

get_port_rules port_rule_exists set_port_rule remove_port_rule

工具

get_host_info get_user_info bind_user_domains_local request_user_input end_workflow delay send_email exec_sql（仅管理端）

结语

自定义工作流 = JavaScript + 宝塔 API + 一点点幂等思维。系统已提供 960 行注释完整的「一键部署小氢云脚本」作为范本：配置区改常量、工具函数原样复制、八步流程按需删减，就是你的生产脚本。

管理端 工作流 → 使用教程 还有可复制的短示例；遇到参数不确定，左侧 操作参考 → 点函数名看详情。

现在就去： 新建工作流 → 粘贴第 6 节代码 → 填主机 ID → 运行。

小氢云商城自定义路由系统完整使用教程

适用版本：小氢云商城系统（Go 后端 + 管理后台 web-antd）
阅读对象：站长、运营、二次开发者
最后更新：2026-05-29

一、这套「路由系统」到底是什么？

在小氢云商城里，自定义路由映射系统（后台菜单：路由映射管理）是一套无需改代码、无需重新打包前端就能上线新页面的能力。

你可以把它理解成：

用户访问 URL  →  系统查映射表  →  读取 doc 目录文件 / 装修配置  →  渲染页面

典型用途包括：

• 落地页、活动页、品牌介绍页
• 独立 API 文档页、帮助中心
• 绑定独立域名做品牌站首页
• 绑定「网站装修项目」做可视化拖拽页面
• 付费内容页（会员专享资料、教程等）

和 Vue Router 的区别： PC/PE 前端里的 Vue Router 管的是商城 SPA 内部跳转；本文讲的是服务端级别的自定义路由，直接由 Go 中间件拦截 HTTP 请求并返回内容，SEO 友好、可独立访问。

二、整体架构（建议先建立心智模型）

flowchart TD
    A[用户请求 /promo/sale] --> B{是否为 /api/* 或后台路径?}
    B -->|是| C[放行给 API / 静态资源]
    B -->|否| D[CustomRouteMiddleware 中间件]
    D --> E{Redis 缓存命中?}
    E -->|否| F[查 MySQL sky_route_mapping]
    F --> G[写入 Redis 永久缓存]
    E -->|是| H[读取映射配置]
    G --> H
    H --> I{数据源类型}
    I -->|file| J[读取 doc 下 HTML/JS/CSS/PHP 等]
    I -->|decoration| K[读取装修项目 JSON 配置]
    J --> L{访问控制}
    K --> L
    L -->|需登录/付费| M[拦截并展示登录/付费页]
    L -->|通过| N[占位符替换 + 静态路径重写 + 返回内容]

核心存储

缓存键规则

键名 = route_mapping: + md5(全局配置 zhuzhan + 路由路径)
值   = 文件相对路径，如 promo/sale.html

创建、更新、删除映射时系统会自动维护 Redis；也可在后台点击 「刷新缓存」 批量同步。

三、功能清单（一张表看懂能做什么）

四、快速上手：5 分钟发布第一个单页

步骤 1：进入管理后台

路径：系统管理 → 路由映射管理（或全局搜索「路由映射」）。

步骤 2：准备页面文件

方式 A — 后台在线创建（推荐新手）

1. 点击 「浏览文件」
2. 在 doc 目录下新建文件夹，如 pages
3. 新建文件 welcome.html，粘贴下方【完整单页示例】代码
4. 保存

方式 B — 服务器手动上传

# 在后端程序同级目录
mkdir -p doc/pages
cp welcome.html doc/pages/welcome.html

doc 目录若不存在，系统会在首次浏览文件时自动创建。

步骤 3：添加路由映射

点击 「添加路由」，填写：

保存后，访问：

https://你的域名/welcome

即可看到页面。

步骤 4：验证

• 页面标题、Logo 等占位符是否被正确替换
• 打开浏览器开发者工具 → Network，确认 CSS/JS 加载 200
• 后台列表中「访问统计」是否增加

五、完整单页 HTML 示例（可直接复制使用）

将以下代码保存为 doc/pages/welcome.html，并映射路由 /welcome：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>[title] - 欢迎页</title>
  <meta name="keywords" content="[seo_keywords]" />
  <meta name="description" content="[seo_description]" />
  <link rel="icon" href="[favicon]" />
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      color: #fff;
    }
    .card {
      background: rgba(255,255,255,0.95);
      color: #333;
      border-radius: 16px;
      padding: 48px 40px;
      max-width: 520px;
      width: 90%;
      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
      text-align: center;
    }
    .logo { width: 64px; height: 64px; border-radius: 12px; margin-bottom: 20px; }
    h1 { font-size: 28px; margin-bottom: 12px; }
    p { color: #666; line-height: 1.8; margin-bottom: 24px; }
    .meta { font-size: 13px; color: #999; margin-bottom: 32px; }
    .btn {
      display: inline-block;
      padding: 12px 32px;
      background: #667eea;
      color: #fff;
      text-decoration: none;
      border-radius: 8px;
      font-weight: 600;
      transition: transform 0.2s, box-shadow 0.2s;
    }
    .btn:hover { transform: translateY(-2px); box-shadow: 0 8px 20px rgba(102,126,234,0.4); }
    footer { margin-top: 32px; font-size: 12px; color: #bbb; }
  </style>
</head>
<body>
  <div class="card">
    <img class="logo" src="[logo]" alt="Logo" onerror="this.style.display='none'" />
    <h1>欢迎来到 [title]</h1>
    <p>这是通过<strong>自定义路由系统</strong>发布的独立单页。<br/>无需修改前端代码，后台配置即可上线。</p>
    <div class="meta">
      当前路由：<code>[router]</code><br/>
      站点地址：<a href="[base_url]">[base_url]</a><br/>
      建站时间：[site_time]
    </div>
    <a class="btn" href="[base_url]">进入商城首页</a>
    <footer>
      [RecordNumber] [PoliceRecordNumber]
    </footer>
  </div>

  <script>
    // 元数据占位符已被 Unicode 转码，可安全嵌入
    var routeMeta = "[元数据]";
    if (routeMeta && routeMeta !== "[元数据]") {
      try {
        var meta = JSON.parse(routeMeta);
        console.log('路由元数据:', meta);
      } catch (e) {}
    }
    console.log('自定义路由页面加载成功，路径:', '[router]');
  </script>
</body>
</html>

这个示例演示了什么？

1. 占位符自动替换：[title]、[logo]、[base_url] 等来自系统配置
2. 纯 CSS 单页：无外部依赖，复制即用
3. 元数据读取：若在后台配置了 Metadata，可通过 [元数据] 在 JS 中使用
4. 备案信息：[RecordNumber]、[PoliceRecordNumber] 自动填充

六、占位符（变量）完整列表

在 所有文本格式文件（HTML、JS、CSS、JSON、TXT、PHP 等）中，以下占位符会在访问时自动替换：

注意：二进制文件（图片等）不会做占位符替换，避免损坏文件。

七、静态资源：为什么你的 CSS/JS 能自动加载？

假设你映射了 /landing → campaign/index.html，且文件结构为：

doc/
└── campaign/
    ├── index.html
    ├── assets/
    │   ├── app.js
    │   └── style.css
    └── static/
        └── banner.png

当 index.html 中引用：

<link rel="stylesheet" href="/assets/style.css" />
<script src="/assets/app.js"></script>

系统会自动重写路径为：

/landing/assets/style.css
/landing/assets/app.js

并从 doc/campaign/assets/ 目录读取文件返回。

支持的静态目录前缀

/assets/、/static/、/js/、/css/、/images/、/img/、/fonts/、/libs/、/lib/ 等。

最佳实践

• 把静态资源放在 HTML 同级或子目录，不要散落到 doc 根目录
• 打包 UniApp/H5 项目时，直接解压到 doc/某路由名/ 下即可
• 路径写 /assets/xxx 即可，系统会自动加路由前缀

八、进阶用法

8.1 域名映射（独立品牌站）

场景：shop.example.com 是商城，brand.example.com 想展示品牌首页。

配置步骤：

1. DNS 将 brand.example.com A 记录解析到服务器 IP
2. 后台添加映射：
   • 映射方式：通过域名
   • 域名：brand.example.com
   • 文件路径：brand/home.html
3. 用户访问 https://brand.example.com/ 时渲染该页面

/api/*、/static/* 等非根路径仍正常走后端，不影响接口。

8.2 绑定网站装修项目

场景：已在「网站装修」里拖拽好了 PC/手机页面，想挂到自定义 URL。

1. 数据源类型选 「网站装修项目」
2. 选择对应装修项目 ID
3. 保存后，PC 端 SPA 的 DynamicRoute.vue 会读取装修 JSON 并渲染组件树

装修类型不走直接 HTML 返回，而是注入到前端 SPA 的 sessionStorage，由 Vue 组件渲染。

8.3 PHP 动态页面

1. 在 网站设置 → 基础设置 配置 PHP 解释器路径
2. 上传 doc/api/hello.php
3. 映射 /api-demo → api/hello.php

系统会用 CLI 模式执行 PHP，并传递 HTTP 上下文（Method、Headers、Body 等）。

安全限制：exec、eval、shell_exec、system 等高危函数默认禁用。

8.4 强制登录 & 付费访问

若全局关闭了用户系统（user_code = false），强制登录和付费功能不会生效。

8.5 元数据 Metadata（动态表单）

Metadata 是一个 JSON 数组，描述表单组件（input、select、radio 等）。

后台操作：添加路由 → 元数据 → 「可视化配置」。

页面中使用：

<script>
  var fields = JSON.parse("[元数据]");
  // fields 是表单组件数组，可动态渲染表单
</script>

系统还会将 Metadata 写入 Cookie（键名 route_meta_ + md5(域名+路由)），有效期 30 天，供跨页面读取。

8.6 设备类型分流

同一 URL，可为 PC 和手机配置不同映射：

• /promo + 设备类型 pc → promo/pc.html
• /promo + 设备类型 pe → promo/mobile.html

系统通过 User-Agent 自动识别设备；调试时可加 ?force_device=pc 或 ?force_device=pe 强制指定。

九、后台文件管理 API（开发者参考）

除可视化「浏览文件」外，还提供完整文件操作接口（均需管理员 Token）：

创建映射示例（curl）

TOKEN="你的管理员Token"

curl -X POST http://127.0.0.1:8080/api/admin/route-mapping/create \
  -H "Content-Type: application/json" \
  -H "admin-token: Bearer $TOKEN" \
  -d '{
    "route": "/welcome",
    "route_type": "route",
    "file_path": "pages/welcome.html",
    "source_type": "file",
    "title": "欢迎页",
    "status": 1,
    "device_type": "def",
    "force_login": 0,
    "is_paid": 0
  }'

十、导入 / 导出（批量迁移）

导出：勾选路由 → 点击「导出」→ 得到 JSON 配置文件。

导入规则：

• 按「路由路径 + 设备类型」判重
• 已存在则更新，不存在则新建
• 支持 JSON 文件或远程 URL 导入

适合从测试环境迁移到生产环境，或备份路由配置。

十一、请求处理优先级（排查问题时必看）

中间件 CustomRouteMiddleware 的执行顺序：

1. 跳过 /api/*、管理后台路径、砍价分享页
2. 静态资源路径 → 尝试从 doc 目录匹配
3. 根路径 / → 优先尝试域名映射
4. 按路由路径精确匹配（/promo 与 /promo/ 等价）
5. 父路由静态资源 → 如 /landing/css/style.css 找 /landing 映射
6. 未命中 → 交给 SPA 的 NoRoute 处理（404 或装修兜底）

访问控制优先级

1. 全局强制登录中间件
2. 路由级强制登录
3. 路由级付费访问

十二、常见问题 FAQ

Q1：访问自定义路由返回 404？

检查清单：

• 路由映射状态是否为 启用
• 文件路径是否正确（相对于 doc，不含 doc/ 前缀）
• doc 目录下文件是否真实存在
• 设备类型是否匹配（PC 页设置了 pe -only 时，电脑访问会 404）
• 点击「刷新缓存」后重试

Q2：改了 HTML 但页面没变化？

• 文件内容不走 Redis 缓存，改完应即时生效
• 若仍不变，检查浏览器缓存（Ctrl+F5 / Cmd+Shift+R）
• 若改了映射配置本身，需刷新路由缓存

Q3：CSS/JS 404？

• 确认静态资源在 HTML 同级目录的 assets/ 或 static/ 下
• HTML 里用 /assets/xxx 相对根路径写法，系统会自动加路由前缀
• 不要手动写完整路由前缀（除非你知道自己在做什么）

Q4：强制登录设置了但不生效？

• 检查 用户系统 是否开启（网站设置 → 用户系统）
• 用户系统关闭时，后台会显示「无效」标签

Q5：能和商城 Vue 路由冲突吗？

• 自定义路由优先级低于 /api/* 和后台路径
• 与 PC SPA 路由：若后端中间件已命中并返回内容，则不会进入 Vue；未命中则走 SPA 的 DynamicRoute.vue 兜底
• 建议：自定义路由使用 /promo/、/landing/ 等独立前缀，避免与商城内置路径冲突

Q6：doc 目录在哪？

与后端可执行程序同级，例如：

/opt/xqy/
├── server          # 后端程序
├── doc/            # ← 这里
│   └── pages/
│       └── welcome.html
└── static/

十三、推荐目录结构

 doc/
 ├── pages/           # 通用单页
 │   ├── about.html
 │   └── contact.html
 ├── campaign/        # 活动页（含静态资源子目录）
 │   ├── index.html
 │   └── assets/
 ├── docs/            # 文档
 │   └── api.html
 └── brand/           # 域名映射专用
     └── home.html

十四、安全注意事项

1. 禁止路径遍历：文件路径不允许 ..，无法访问 doc 外文件
2. 管理接口鉴权：所有配置/文件操作需管理员 Token
3. PHP 高危函数禁用：生产环境务必配置解释器并审查 PHP 代码
4. 付费页：涉及资金，修改价格前确认已购用户权益策略
5. 唯一路由：同一路由 + 设备类型不可重复，防止映射冲突

十五、总结

自定义路由系统是小氢云商城最灵活的页面发布通道——运营同学可以独立上线页面，开发同学可以对接 PHP/H5 整包，无需每次改代码发版。

附录：数据库表字段速查

sky_route_mapping 主要字段：

本文由小氢云商城技术团队整理，基于系统源码与后台「路由映射管理」模块编写。如有疑问，欢迎在评论区留言。

小氢云商城模板开发完全指南

本文面向第三方模板开发者与站点二次开发者，系统梳理小氢云商城（Go 架构）下的模板开发规范、接口调用方式与上架流程。读完本文，你应该能独立完成一个可安装的静态模板，并正确对接商城核心业务接口。

一、先搞清楚：模板是什么

在小氢云商城里，「模板」指的是替换或扩展前台展示层的前端工程。用户访问商城时，系统通过路由映射把 URL 指向你打包好的 index.html，你的页面再通过 REST API 与后端通信，完成商品展示、下单、支付、查单等完整链路。

当前系统支持两类模板形态：

小氢云商城后端为 Go + Gin，接口统一走 /api/*。PHP 模板中的 /?mod=route&p=Goods 等旧式路由，在新系统中应改为前端路由 + REST API 的方式实现。

二、模板目录结构规范

2.1 静态 SPA 模板（主流方式）

从模板商店安装后，系统会将 zip 包解压到 doc/{template_slug}/ 目录，并自动创建路由映射。

标准目录结构：

my-template/
├── index.html          # 入口文件（必需，文件名必须为 index）
├── index.png           # 预览图（建议 800×600px，上架用）
├── assets/             # JS / CSS 打包产物（UniApp / Vite 默认目录）
│   ├── index-xxx.js
│   └── index-xxx.css
├── static/             # 图片、字体等静态资源（可选）
│   └── images/
└── conf.json           # 模板配置（可选，见下文）

硬性要求：

1. 包内必须存在名为 index 的首页文件（index.html / index.htm / index.php，优先 .html）
2. template_slug 在授权站配置，仅允许英文和数字，全局唯一
3. 静态资源与 index.html 放在同一目录树下，便于路由中间件自动解析

2.2 经典 PHP 模板（晴玖兼容）

若你沿用晴玖商城模板规范，目录如下：

template/{应用标识}/
├── index.php         # 模板入口
├── index.png         # 预览图
├── route.php         # 路由跳转（旧式页面导航）
├── conf.json         # 模板配置
└── help.html         # 帮助文档（有扩展功能时建议提供）

route.php 示例（旧式跳转，新开发建议用前端路由替代）：

<?php
switch ($_GET['p']) {
    case 'Goods':
        header("Location: " . ROOT_DIR . "#/pages/shop/shop?gid=" . $_GET['gid']);
        break;
    case 'Order':
        header("Location: " . ROOT_DIR . "#/pages/order/order");
        break;
    default:
        header("Location: " . ROOT_DIR);
        break;
}

三、模板配置文件 conf.json

conf.json 让站长在后台可视化修改模板参数，无需改代码。

{
    "name": "极简商城模板",
    "version": "1.0.0",
    "type": "1",
    "content": "一款简洁现代的商城前台模板",
    "extend": [
        {
            "type": 1,
            "name": "主题色",
            "value": "#1890ff",
            "Tips": "全局主色调，支持 HEX 色值"
        },
        {
            "type": 2,
            "name": "首页布局",
            "value": "1",
            "data": {
                "1": "单列瀑布流",
                "2": "双列网格",
                "3": "分类优先"
            }
        }
    ]
}

四、接口调用规范

4.1 基础约定

统一响应结构：

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

4.2 获取站点基础信息（模板初始化必调）

模板加载后，第一件事应拉取站点配置，用于渲染 Logo、公告、默认商品图、登录状态等。

// 获取网站基础信息（含 sitename、notice、def_img、User 等）
const res = await fetch('/api/inform', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }
});
const { code, data } = await res.json();

// 获取前端公共配置
const config = await fetch('/api/getConfig', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }
});

/api/inform 支持可选认证：携带 user-token 时返回当前用户信息；不传则为游客模式。

4.3 用户登录与 Token 管理

登录：

const res = await fetch('/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'demo',
    password: '123456',
    code: ''        // 验证码（若后台开启）
  })
});
const { code, data } = await res.json();
if (code === 200) {
  localStorage.setItem('user-token', data.token);
}

携带 Token 发起请求：

const token = localStorage.getItem('user-token');

const res = await fetch('/api/getUserInfo', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'user-token': `Bearer ${token}`
  }
});

Token 无感刷新：

当接口返回 code === 401 时，调用 POST /api/refresh-token（同样携带 user-token 头），拿到新 token 后重试原请求。

4.4 封装通用请求函数（推荐）

const API_BASE = window.location.origin;

async function api(url, params = {}, method = 'POST') {
  const token = localStorage.getItem('user-token');
  const headers = { 'Content-Type': 'application/json' };
  if (token) headers['user-token'] = `Bearer ${token.trim()}`;

  const options = { method, headers };
  if (method !== 'GET') options.body = JSON.stringify(params);

  const res = await fetch(API_BASE + url, options);
  const data = await res.json();

  if (data.code === 401) {
    // 触发登录弹窗或跳转登录页
    throw new Error('登录已过期');
  }
  if (data.code !== 200 && data.code !== 1) {
    throw new Error(data.msg || '请求失败');
  }
  return data;
}

// 使用示例
const goods = await api('/api/getGoods', { cid: 1, page: 1, limit: 20 });
const detail = await api('/api/getGoodsById', { id: 123 });

4.5 核心业务接口速查

商品与分类

下单与订单

支付

用户中心

完整接口清单见项目 doc/api/client/ 目录，按模块分为商品、订单、支付、认证等文档。

4.6 图片地址处理

• 本地上传图片路径形如 /static/img/xxx.png，直接拼接站点域名即可，无需走代理
• 相对路径统一用 window.location.origin 拼接，避免硬编码域名
• 商品默认图优先取 /api/inform 返回的 def_img 字段

function resolveImage(url) {
  if (!url) return '';
  if (url.startsWith('http')) return url;
  return window.location.origin + (url.startsWith('/') ? url : '/' + url);
}

五、路由映射与静态资源（关键！）

模板安装后，系统会在路由映射中创建一条记录（默认路由 /，初始状态为关闭，需站长手动启用）。

5.1 子路由下的静态资源自动重写

若你的模板映射到 /myshop（非根路径），系统会自动重写 HTML 中的绝对路径：

<!-- 打包原始 -->
<script src="/assets/index.js"></script>

<!-- 访问 /myshop 时自动变为 -->
<script src="/myshop/assets/index.js"></script>

支持自动重写的目录前缀：/assets/、/static/、/js/、/css/、/images/、/img/、/fonts/、/libs/、/lib/

5.2 获取当前路由前缀

HTML 中可使用 [router] 占位符，服务端渲染时替换为当前路由：

<div id="app" data-base="[router]"></div>
<!-- 映射到 /myshop 时变为 data-base="/myshop" -->

JS 中读取：

const basePath = document.getElementById('app').dataset.base || '';
// 用于 Vue Router 的 base 配置

5.3 常见踩坑

六、开发流程与上架规范

6.1 完整开发流程

1. 在授权站创建模板项目，配置 template_slug
       ↓
2. 本地开发前端（Vue / UniApp H5 等）
       ↓
3. 打包产物确保含 index.html + assets/
       ↓
4. 本地测试：手动创建路由映射指向打包目录
       ↓
5. 打包 zip 上传授权站，提交审核
       ↓
6. 站长在「模板商店」安装 → 启用路由映射

6.2 本地调试建议

方式一：路由映射调试（推荐）

1. 将打包产物放到后端 doc/my-template/ 目录
2. 管理后台 → 路由映射 → 新建映射
   • 路由：/my-template
   • 文件路径：my-template/index.html
   • 设备类型：pc / pe / def
   • 状态：启用
3. 访问 http://127.0.0.1:8080/my-template 验证

方式二：开发服务器 + API 直连

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': 'http://127.0.0.1:8080'
    }
  }
}

6.3 提审清单

提交模板商店审核前，请逐项确认：

• 包含 index.html（或 index.htm / index.php）入口文件
• 预览图 index.png（建议 800×600px）
• 路由映射测试通过，静态资源全部 200
• 商品列表、详情、下单、查单核心链路跑通
• 登录 / 游客双模式均正常
• 移动端适配（若 template_device=mobile）
• conf.json 格式正确（若有配置项）
• 帮助文档 help.html（若有扩展功能）
• 无硬编码第三方域名、无安全隐患

上架参数：

七、扩展开发方式

7.1 插件式扩展（复杂功能）

需要拼团、砍价、自定义支付等能力时，建议开发应用商店插件，在模板中通过接口调用：

GET ?AppApies&identification={插件标识}&name={方法名}

插件控制器规范：

/includes/lib/soft/controller/{标识}/index.php

7.2 内置式扩展（简单功能）

在模板包内直接新增 PHP 文件，通过 URL 访问：

/?mod={扩展文件名}

查找顺序：

1. /template/{应用标识}/{扩展文件}.php
2. /template/default/{扩展文件}.php

新架构下更推荐纯前端 + REST API 方案，PHP 扩展仅作兼容保留。

八、开发规范与最佳实践

8.1 代码规范

1. 不要硬编码站点域名，统一用 window.location.origin
2. 图片路径走 /static/img/ 直链，不走 /api/image/proxy
3. 富文本渲染（UniApp PE 端）统一用 <u-parse :content="xxx" :selectable="true">
4. 登录态优先读 localStorage，401 时引导重新登录
5. 接口兼容同时判断 code === 200 和 code === 1

8.2 性能建议

• 静态资源打包压缩，图片适当 WebP
• 商品列表分页加载，避免一次拉全量
• 站点配置（/api/inform）可缓存 60 秒，开发模式建议 1 秒
• 按需加载路由模块，控制首屏 JS 体积

8.3 安全建议

• 不在前端存储敏感信息（密码、API 密钥）
• 用户输入做 XSS 过滤后再渲染
• 涉及资金的接口必须带 Token，不做前端金额计算终裁

九、快速上手示例：最小可用模板

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>我的商城模板</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: -apple-system, sans-serif; background: #f5f5f5; }
    .header { background: #fff; padding: 16px; text-align: center; box-shadow: 0 1px 4px rgba(0,0,0,.08); }
    .goods-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 12px; padding: 16px; }
    .goods-card { background: #fff; border-radius: 8px; overflow: hidden; cursor: pointer; }
    .goods-card img { width: 100%; aspect-ratio: 1; object-fit: cover; }
    .goods-card .info { padding: 8px 12px; }
    .goods-card .name { font-size: 14px; color: #333; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
    .goods-card .price { color: #ff4d4f; font-weight: 600; margin-top: 4px; }
  </style>
</head>
<body>
  <div class="header"><h1 id="site-name">加载中...</h1></div>
  <div class="goods-list" id="goods-list"></div>

  <script>
    const API = window.location.origin;

    async function api(url, params = {}) {
      const token = localStorage.getItem('user-token');
      const headers = { 'Content-Type': 'application/json' };
      if (token) headers['user-token'] = 'Bearer ' + token.trim();
      const res = await fetch(API + url, { method: 'POST', headers, body: JSON.stringify(params) });
      return res.json();
    }

    async function init() {
      // 1. 站点信息
      const site = await api('/api/inform');
      if (site.code === 200 || site.code === 1) {
        document.getElementById('site-name').textContent = site.data?.sitename || '商城';
      }

      // 2. 商品列表
      const goods = await api('/api/getGoods', { page: 1, limit: 20 });
      const list = goods.data?.list || goods.data || [];
      const container = document.getElementById('goods-list');

      list.forEach(item => {
        const img = item.image?.startsWith('http') ? item.image : API + (item.image || '/static/img/default.png');
        container.innerHTML += `
          <div class="goods-card" onclick="location.href='?id=${item.id}'">
            <img src="${img}" alt="${item.name}" loading="lazy">
            <div class="info">
              <div class="name">${item.name}</div>
              <div class="price">¥${item.price}</div>
            </div>
          </div>`;
      });
    }

    init().catch(err => console.error('初始化失败:', err));
  </script>
</body>
</html>

将上述文件保存为 index.html，配合路由映射即可在本地验证。

十、相关资源

总结

小氢云商城模板开发的本质是：用任意前端技术栈打包出 SPA，通过路由映射挂载到商城域名下，用标准 REST API 驱动业务。

记住三个关键点：

1. 入口文件必须叫 index，静态资源与之间目录
2. 接口走 /api/*，认证头用 user-token: Bearer {token}
3. 非根路由映射时，依赖系统自动重写 /assets/ 等静态路径

按本文规范开发并通过提审清单自检，你的模板就能顺利上架并被站长一键安装使用。

如有疑问，欢迎在评论区留言或加入开发者交流群。

Apache 反向代理下配置 WebSocket 完整教程

适用场景：后端为 Go 二进制（如监听 127.0.0.1:8091），前面使用 Apache（宝塔面板常见）做 HTTP/HTTPS 反向代理。
不装 Nginx 也可以，但 必须在 Apache 里单独处理 WebSocket 握手，否则会出现实时消息、售后聊天、通知推送连不上的问题。

一、先搞懂：为什么会出现这条报错？

后端日志里若看到类似：

WebSocket升级失败: websocket: the client is not using the websocket protocol:
'upgrade' token not found in 'Connection' header

含义是：到达 Go 的请求是普通 HTTP GET，不是 WebSocket 握手。

常见原因分三类：

结论：你即使用二进制启动 Go、不装 Nginx，只要域名前面有 Apache 反代，就必须给 WebSocket 单独加规则。

二、架构示意

浏览器 --wss/https--> Apache (80/443) --ws/http--> Go 二进制 (127.0.0.1:8091)
普通页面/API：ProxyPass http://
WebSocket：需 Upgrade 转发到 ws://

本项目中 WebSocket 入口示例：

• 售后/全局消息：/api/ws/aftersale?token=你的JWT
• 接单大厅：/api/ws/lobby?token=你的JWT

前端在 HTTPS 页面下应连接：wss://你的域名/api/ws/aftersale?token=xxx

三、前置条件检查清单

在改配置前，请确认：

1. Go 服务已监听 8091（或你自定义端口），本机可访问：
   curl http://127.0.0.1:8091/health
2. 防火墙/安全组 已放行对外 80、443（Apache）；8091 通常只本机访问，不必对公网开放。
3. 站点已配置反代 到 http://127.0.0.1:8091/（你当前的宝塔写法）。
4. 若站点启用 HTTPS，必须同时改 443 的 VirtualHost，不能只改 80。

四、第一步：启用 Apache 模块（宝塔）

路径：软件商店 → Apache → 设置 → 模块 / 加载模块

请确保已启用：

• proxy
• proxy_http
• proxy_wstunnel（WebSocket 关键模块）
• rewrite

保存后 重载配置 或 重启 Apache。

若没有 proxy_wstunnel，RewriteRule ... ws://... [P] 无法生效，WebSocket 一定失败。

五、第二步：修改站点 Apache 配置（核心）

5.1 找到配置位置

宝塔：网站 → 你的站点 → 设置 → 配置文件（Apache）。

找到类似段落：

# HTTP反向代理相关配置开始 >>>
...
# HTTP反向代理相关配置结束 <<<

5.2 推荐完整写法（80 端口示例）

将中间反代段 整体替换 为：

# HTTP反向代理相关配置开始 >>>
<IfModule mod_proxy.c>
    ProxyRequests Off
    SSLProxyEngine on
    ProxyPreserveHost On

    # ---------- WebSocket 升级转发（必须） ----------
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/(.*) ws://127.0.0.1:8091/$1 [P,L]

    # ---------- 普通 HTTP 请求 ----------
    ProxyPass / http://127.0.0.1:8091/
    ProxyPassReverse / http://127.0.0.1:8091/
</IfModule>
# HTTP反向代理相关配置结束 <<<

说明：

• 8091 改成你 Go 程序实际监听端口。
• RewriteRule 必须在 ProxyPass 之前生效：带 Upgrade: websocket 的请求走 ws://，其余走普通 HTTP。
• [P,L] 表示通过代理模块处理并停止后续规则。

5.3 你原来的配置缺了什么？

仅下面两行时，页面和 API 正常，WebSocket 会失败：

ProxyPass / http://127.0.0.1:8091/
ProxyPassReverse / http://127.0.0.1:8091/

因为 Apache 默认不会把 WebSocket 握手头转发成后端所需的 Connection: Upgrade。

六、HTTPS（443）站点也要同样配置

若用户访问 https://pp.example.com，浏览器 WebSocket 使用 wss，走的是 443 的 VirtualHost。

请务必在 SSL 站点 的配置里加入 与 80 相同 的 RewriteEngine + ProxyPass 段。

只改 80、不改 443 的典型现象：

• 网站能打开（https）
• 接口大部分正常
• 实时消息、未读气泡、聊天一直连不上

七、验证是否配置成功

7.1 浏览器开发者工具

1. 登录你的前台/后台页面。
2. 按 F12 → 网络 (Network) → 筛选 WS。
3. 找到类似：/api/ws/aftersale?token=...
4. 正常状态应为：101 Switching Protocols（已建立 WebSocket）。

若显示失败、一直 pending、或很快断开，优先检查 Apache 模块与 443 配置。

7.2 看 Go 日志

配置正确后：

• 不应再频繁刷 upgrade token not found（偶发误访问可忽略）。
• 连接成功会有业务侧日志（视项目而定）。

7.3 本机直连对比（排查用）

在服务器上：

curl http://127.0.0.1:8091/health

若本机正常、域名不正常，问题在 Apache 反代层，不是 Go 程序本身。

八、与「不装 Nginx、二进制启动」的关系

你当前属于第三种：Apache 反代 + Go 二进制，按本文配置即可，无需再装 Nginx。

九、前端连接注意事项（开发参考）

1. 协议跟随页面：HTTPS 页面必须用 wss://，HTTP 用 ws://。
2. Token 建议 URL 编码：token=${encodeURIComponent(jwt)}，避免特殊字符截断。
3. 路径与后端一致：例如 /api/ws/aftersale。

示例：

const wsUrl = `wss://${location.host}/api/ws/aftersale?token=${encodeURIComponent(token)}`
const ws = new WebSocket(wsUrl)

十、常见问题 FAQ

Q1：配了 Rewrite 仍连不上？

• 确认 proxy_wstunnel 已启用并重载 Apache。
• 确认改的是 用户实际访问的端口（https 改 443）。
• 确认 Go 监听地址是 127.0.0.1:8091 与配置一致。

Q2：只有 WebSocket 报错，网站正常？

说明 HTTP 反代 OK，仅缺 WS 规则，按第五节补 RewriteEngine 即可。

Q3：可以用宝塔「反向代理」界面吗？

可以填目标 URL http://127.0.0.1:8091，有 WebSocket 开关请打开；但 Apache 环境下仍建议在 配置文件 中保留 RewriteRule，最稳妥。

Q4：需要给 8091 开端口给外网吗？

通常 不需要。外网只访问 80/443，由 Apache 转发到本机 8091。

Q5：和 Nginx 的配置等价吗？

思路相同：都要转发 Upgrade 和 Connection。Nginx 写法是 proxy_set_header Upgrade $http_upgrade; 等；Apache 用本文 RewriteRule + proxy_wstunnel。

十一、配置模板速查

仅本机 Go、无反代： ws://服务器IP:8091/api/ws/aftersale?token=xxx

域名 + Apache + HTTPS： wss://你的域名/api/ws/aftersale?token=xxx

Apache 反代核心三行逻辑：

1. RewriteEngine On
2. 检测 Upgrade=websocket → 转发到 ws://127.0.0.1:端口
3. 其余请求 ProxyPass 到 http://127.0.0.1:端口

十二、小结

• 不装 Nginx、二进制跑 Go 完全可行。
• 只要 Apache（宝塔）反代 到你的 Go 端口，就必须配置 WebSocket 升级转发。
• 核心是启用 proxy_wstunnel，并添加 RewriteRule ... ws://... [P,L]。
• HTTPS 站点（443） 与 HTTP（80）要同步修改。
• 用浏览器 WS 面板看到 101 即表示成功。

按本文操作后，实时聊天、消息推送、接单大厅等依赖 WebSocket 的功能即可与 API 一样稳定对外服务。

本文由小氢云相关部署实践整理，如有环境差异（OpenLiteSpeed、CDN 等）可在评论补充。

自带节点函数

系统里提供了一些自带的节点函数，比如

点一下节点函数就可以查看详细信息

我给你们写了一个 一键部署 Go 程序的脚本，你们可以参考一下，功能正常可以直接使用

脚本里有一段是上传文件，用的是 @，@的意思就是 /doc 目录！也就是下面的这张图，你要把你部署的程序安装包放进去

/**
 * jjwk-service 一键部署工作流
 *
 * 执行顺序（幂等设计，可重复运行）：
 *   [01] 初始化 → 拉取主机/用户信息，弹窗选择或输入绑定域名
 *   [02] 部署包 → 远程无 zip 才上传，上传后二次校验
 *   [03] 解压   → 二进制不存在，或刚上传且 forceUnzipAfterUpload=true 时解压
 *   [04] 数据库 → 不存在则创建，存在则复用主机记录中的账号信息
 *   [05] 配置   → 写 config.yaml（数据库 + app.base_url）
 *   [06] 端口   → 防火墙放行服务端口（已放行则跳过）
 *   [07] Go项目 → 查重后创建/跳过，本地绑定域名，启动项目
 *   [08] 通知   → 有邮箱则发 HTML 邮件汇总
 *
 * 注意：
 *   - 工作流 API 参数名（host_id、host_source 等）为 snake_case，与后端一致
 *   - 脚本内部变量统一 camelCase
 *   - hostId 可在编辑器顶部「执行主机 ID」覆盖，此处为默认值
 */

// ========== 配置 ==========

/** 目标主机 ID（与编辑器顶部 host_id 注入二选一，此处为脚本内默认值） */
const hostId = "";

/** 本地部署包路径（@/ 表示系统 doc 目录下的相对路径） */
const localPackagePath = "@/jjwk-service-v2.4.8-install.zip";

/** 上传到远程站点目录后的 zip 文件名 */
const packageFileName = "jjwk-service-v2.4.8-install.zip";

/** 解压后的 Go 二进制文件名（需与 zip 内一致） */
const binaryFileName = "jjwk-service";

/** 主机未配置端口时的默认监听端口 */
const defaultPort = 9001;

/**
 * 上传新包后是否强制重新解压
 * true  = 即使二进制已存在，刚上传完也会覆盖解压
 * false = 二进制已存在则跳过解压
 */
const forceUnzipAfterUpload = true;

// ========== 日志工具 ==========

/** 全局递增序号，供 logInfo 使用 */
var logSequence = 0;

/** 序号补零：1 → "01"，12 → "12" */
function padLogIndex(value) {
  return value < 10 ? "0" + value : String(value);
}

/**
 * 主步骤日志，自动递增序号
 * 示例：[03] 远程包已存在，跳过上传
 */
function logInfo(message) {
  logSequence += 1;
  console.log("[" + padLogIndex(logSequence) + "] " + message);
}

/**
 * 子步骤/细节日志，带树形缩进，不占用主序号
 * 示例：         └─ siteRootPath: /www/wwwroot/xxx
 */
function logDetail(message) {
  console.log("         └─ " + message);
}

/**
 * 阶段标题日志，使用固定阶段号（01~08），便于对照流程图
 * 示例：[02] 检测并上传部署包
 */
function logPhase(phaseNo, title) {
  console.log("[" + padLogIndex(phaseNo) + "] " + title);
}

// ========== 通用工具 ==========

/**
 * 将主机名转为宝塔 Go 项目名
 * 宝塔不允许项目名含 `.` 和 `-`，统一替换为 `_`
 */
function sanitizeGoProjectName(hostName) {
  return String(hostName || "")
    .replace(/\./g, "_")
    .replace(/-/g, "_");
}

/**
 * 将主机名转为 MySQL 库名/用户名
 * MySQL 标识符不支持 `.` 和 `-`，规则同 Go 项目名
 */
function sanitizeDbName(hostName) {
  return String(hostName || "")
    .replace(/\./g, "_")
    .replace(/-/g, "_");
}

/**
 * 生成随机数据库密码（排除易混淆字符 0/O/1/l/I）
 * @param {number} length 密码长度
 */
function randomDbPassword(length) {
  var charset = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789";
  var password = "";
  for (var i = 0; i < length; i++) {
    password += charset.charAt(Math.floor(Math.random() * charset.length));
  }
  return password;
}

/**
 * 规范化用户输入的域名
 * - 去掉首尾空白、末尾 /
 * - 去掉 http(s):// 协议头
 * - 去掉路径部分（只保留 host）
 * 不使用正则匹配协议，避免 Monaco 校验误报
 */
function normalizeDomainInput(value) {
  var normalized = String(value || "").trim();
  while (normalized.length > 0 && normalized.charAt(normalized.length - 1) === "/") {
    normalized = normalized.slice(0, -1);
  }
  var lowerCase = normalized.toLowerCase();
  if (lowerCase.indexOf("https:") === 0) {
    normalized = normalized.slice(6);
    if (normalized.charAt(0) === "/" && normalized.charAt(1) === "/") {
      normalized = normalized.slice(2);
    }
  } else if (lowerCase.indexOf("http:") === 0) {
    normalized = normalized.slice(5);
    if (normalized.charAt(0) === "/" && normalized.charAt(1) === "/") {
      normalized = normalized.slice(2);
    }
  }
  var slashIndex = normalized.indexOf("/");
  if (slashIndex >= 0) {
    normalized = normalized.slice(0, slashIndex);
  }
  return normalized.trim();
}

/**
 * 断言工作流节点返回 status === true，否则抛错中断流程
 * @param {object} actionResult 节点返回值
 * @param {string} actionName   节点名，用于错误信息
 */
function assertActionSuccess(actionResult, actionName) {
  if (!actionResult || actionResult.status !== true) {
    throw new Error(
      actionName + " 失败: " + JSON.stringify(actionResult || { status: false }),
    );
  }
  return actionResult;
}

/**
 * 解析 database_exists 返回值
 * 该节点包装为 { value: true/false, status, code }
 */
function isDatabaseExists(checkResult) {
  return !!(checkResult && checkResult.value === true);
}

// ========== Go 项目查重 ==========

/** 从宝塔 Go 项目对象中提取项目名称（兼容多种字段名） */
function resolveGoProjectName(projectItem) {
  if (!projectItem) {
    return "";
  }
  var configName =
    projectItem.project_config &&
    (projectItem.project_config.project_name ||
      projectItem.project_config.projectName);
  return String(
    projectItem.name ||
    projectItem.project_name ||
    projectItem.projectName ||
    configName ||
    "",
  ).trim();
}

/** 名称比较（忽略大小写） */
function isSameGoProjectName(left, right) {
  return (
    !!String(left || "").trim() &&
    String(left).trim().toLowerCase() === String(right || "").trim().toLowerCase()
  );
}

/** 在列表中查找与当前主机匹配的 Go 项目 */
function findGoProjectInList(projectList, projectName, hostName, siteRootPath) {
  for (var itemIndex = 0; itemIndex < projectList.length; itemIndex++) {
    if (
      isGoProjectMatched(
        projectList[itemIndex],
        projectName,
        hostName,
        siteRootPath,
      )
    ) {
      return projectList[itemIndex];
    }
  }
  return null;
}

/**
 * 创建 Go 项目后校验：以宝塔项目列表为准（get_project_info 可能误判）
 */
function verifyGoProjectExists(projectName, hostName, siteRootPath, retryTimes) {
  var maxRetry = retryTimes == null ? 5 : retryTimes;
  for (var attemptIndex = 0; attemptIndex < maxRetry; attemptIndex++) {
    var matched = findGoProject(projectName, hostName, siteRootPath);
    if (matched) {
      logDetail("Go 项目校验通过: " + resolveGoProjectName(matched));
      return matched;
    }
    if (attemptIndex < maxRetry - 1) {
      logDetail(
        "Go 项目暂未出现在列表（" +
        (attemptIndex + 1) +
        "/" +
        maxRetry +
        "），2 秒后重试…",
      );
      delay({ seconds: 2 });
    }
  }
  throw new Error("Go 项目校验失败，宝塔列表中未找到: " + projectName);
}

/**
 * 统一 get_go_project_list 各种返回结构为数组
 * 兼容 list / items / data / value 等字段
 */
function normalizeGoProjectList(rawList) {
  if (!rawList) {
    return [];
  }
  if (Array.isArray(rawList)) {
    return rawList;
  }
  if (Array.isArray(rawList.list)) {
    return rawList.list;
  }
  if (Array.isArray(rawList.items)) {
    return rawList.items;
  }
  if (Array.isArray(rawList.data)) {
    return rawList.data;
  }
  if (Array.isArray(rawList.value)) {
    return rawList.value;
  }
  return [];
}

/** 从宝塔 Go 项目对象中提取项目路径，去掉末尾 / */
function resolveGoProjectPath(projectItem) {
  return String((projectItem && projectItem.path) || "").trim().replace(/\/+$/, "");
}

/**
 * 按关键字搜索 Go 项目列表（宝塔侧模糊搜索）
 * @param {string} searchKeyword 搜索词，通常为主机名或 sanitize 后的项目名
 * @param {number} resultLimit    最多返回条数
 */
function searchGoProjects(searchKeyword, resultLimit) {
  var keyword = String(searchKeyword || "").trim();
  if (!keyword) {
    return [];
  }
  return normalizeGoProjectList(
    get_go_project_list({
      search: keyword,
      p: 1,
      limit: resultLimit || 10,
      type_id: "",
    }),
  );
}

/**
 * 判断列表中的 Go 项目是否与当前主机匹配
 * 匹配规则（任一满足即可）：
 *   1. 项目名 === sanitizeGoProjectName(hostName)
 *   2. 项目名 === hostName
 *   3. 项目路径 === siteRootPath
 */
function isGoProjectMatched(projectItem, projectName, hostName, siteRootPath) {
  var normalizedSitePath = String(siteRootPath || "").trim().replace(/\/+$/, "");
  var resolvedName = resolveGoProjectName(projectItem);
  var resolvedPath = resolveGoProjectPath(projectItem);
  var sanitizedHostName = sanitizeGoProjectName(hostName);

  if (normalizedSitePath && resolvedPath && resolvedPath === normalizedSitePath) {
    return true;
  }
  if (isSameGoProjectName(resolvedName, projectName)) {
    return true;
  }
  if (isSameGoProjectName(resolvedName, hostName)) {
    return true;
  }
  if (isSameGoProjectName(resolvedName, sanitizedHostName)) {
    return true;
  }
  return false;
}

/**
 * 查找已存在的 Go 项目（避免重复创建）
 * 仅以 get_go_project_list 为准；get_go_project_detail 易误判导致跳过创建后无法启动
 * @returns {object|null} 匹配到的列表项，未找到返回 null
 */
function findGoProject(projectName, hostName, siteRootPath) {
  var searchKeywords = [];
  if (projectName) {
    searchKeywords.push(projectName);
  }
  if (hostName && hostName !== projectName) {
    searchKeywords.push(hostName);
  }
  var sanitizedHostName = sanitizeGoProjectName(hostName);
  if (
    sanitizedHostName &&
    sanitizedHostName !== projectName &&
    sanitizedHostName !== hostName
  ) {
    searchKeywords.push(sanitizedHostName);
  }

  var keywordIndex;
  for (keywordIndex = 0; keywordIndex < searchKeywords.length; keywordIndex++) {
    var projectList = searchGoProjects(searchKeywords[keywordIndex], 100);
    logDetail(
      "get_go_project_list search=" +
      searchKeywords[keywordIndex] +
      " 共 " +
      projectList.length +
      " 条",
    );
    var matched = findGoProjectInList(
      projectList,
      projectName,
      hostName,
      siteRootPath,
    );
    if (matched) {
      logDetail(
        "get_go_project_list 命中: " +
        resolveGoProjectName(matched) +
        " | path=" +
        resolveGoProjectPath(matched),
      );
      return matched;
    }
  }

  var fullList = normalizeGoProjectList(
    get_go_project_list({
      p: 1,
      limit: 1000,
      type_id: "",
    }),
  );
  logDetail("get_go_project_list 全量扫描 共 " + fullList.length + " 条");
  var fullMatched = findGoProjectInList(
    fullList,
    projectName,
    hostName,
    siteRootPath,
  );
  if (fullMatched) {
    logDetail(
      "get_go_project_list 全量命中: " + resolveGoProjectName(fullMatched),
    );
    return fullMatched;
  }

  return null;
}

// ========== 域名处理 ==========

/**
 * 从 get_host_info 返回中解析已绑定域名列表
 * domains 字段可能是 JSON 字符串、数组或逗号分隔文本
 */
function parseBoundDomains(hostInfo) {
  if (!hostInfo) {
    return [];
  }

  var rawDomains = hostInfo.domains;
  var domainList = [];

  if (Array.isArray(rawDomains)) {
    domainList = rawDomains;
  } else if (typeof rawDomains === "string" && rawDomains.trim()) {
    try {
      var parsedDomains = JSON.parse(rawDomains);
      if (Array.isArray(parsedDomains)) {
        domainList = parsedDomains;
      } else if (typeof parsedDomains === "string" && parsedDomains.trim()) {
        domainList = [parsedDomains];
      }
    } catch (parseError) {
      domainList = rawDomains.split(/[,，\s]+/);
    }
  }

  var boundDomains = [];
  for (var domainIndex = 0; domainIndex < domainList.length; domainIndex++) {
    var domainValue = String(domainList[domainIndex] || "").trim();
    if (domainValue) {
      boundDomains.push(domainValue);
    }
  }

  return boundDomains;
}

/**
 * 判断域名是否已在当前主机本地绑定（大小写不敏感）
 * 用于区分「复用已有域名」与「绑定新域名」的日志/邮件文案
 */
function isDomainAlreadyBound(hostInfo, targetDomain) {
  var normalizedTarget = normalizeDomainInput(targetDomain).toLowerCase();
  if (!normalizedTarget) {
    return false;
  }
  var boundDomains = parseBoundDomains(hostInfo);
  for (var domainIndex = 0; domainIndex < boundDomains.length; domainIndex++) {
    if (normalizeDomainInput(boundDomains[domainIndex]).toLowerCase() === normalizedTarget) {
      return true;
    }
  }
  return false;
}

/**
 * 调用 bind_user_domains_local 写入 lh_hosts.domains（不操作宝塔）
 * 后端会自动去重：同主机 / 该用户其他主机已绑定的域名会 skipped
 * @returns {{ domainBound: boolean, bindResult: object }}
 */
function bindDomainLocally(hostInfo, targetDomain) {
  var bindResult = bind_user_domains_local({
    user_id: hostInfo.uid,
    host_id: hostInfo.id,
    domains: [targetDomain],
  });

  if (bindResult.skipped) {
    logDetail("本地绑定跳过（域名已存在）: " + targetDomain);
    return { domainBound: false, bindResult: bindResult };
  }

  logDetail(
    "本地绑定成功: " +
    targetDomain +
    "，当前共 " +
    bindResult.total_count +
    " 个域名",
  );
  return { domainBound: true, bindResult: bindResult };
}

/**
 * 弹窗让用户选择已有域名或输入新域名（combobox 可输入下拉）
 * 暂停工作流等待用户操作；取消则 end_workflow 终止
 * @returns {{ bindDomain: string, appBaseUrl: string }}
 */
function requestBindDomain(hostInfo) {
  var boundDomains = parseBoundDomains(hostInfo);

  // 根据主机 SSL 配置决定 app.base_url 协议
  var enableHttps =
    hostInfo &&
    (hostInfo.ssl_enabled === 1 ||
      hostInfo.ssl_enabled === true ||
      hostInfo.ssl_force_https === 1 ||
      hostInfo.ssl_force_https === true);
  var urlScheme = enableHttps ? "https" : "http";

  // 已绑定域名作为 combobox 下拉选项
  var domainOptions = [];
  for (var optionIndex = 0; optionIndex < boundDomains.length; optionIndex++) {
    domainOptions.push({
      label: boundDomains[optionIndex],
      value: boundDomains[optionIndex],
    });
  }

  var promptContent =
    "请选择已绑定域名，或直接输入新域名，将用于 app.base_url 与 Go 项目";
  if (boundDomains.length === 0) {
    promptContent = "请输入要绑定的域名，将用于 app.base_url 与 Go 项目";
  }

  var inputResult = request_user_input({
    title: "绑定域名",
    content: promptContent,
    input_type: "combobox",
    placeholder: "example.com",
    options: domainOptions,
    required: true,
    field_key: "domain",
  });

  // 用户点击取消 → 优雅结束工作流（非报错）
  if (inputResult.cancelled) {
    end_workflow({ message: "用户取消了域名输入" });
  }

  var selectedDomain = normalizeDomainInput(inputResult.value);
  if (!selectedDomain) {
    throw new Error("域名不能为空");
  }

  var applicationBaseUrl = urlScheme + "://" + selectedDomain;

  logDetail("用户选定域名: " + selectedDomain);
  logDetail("app.base_url: " + applicationBaseUrl);

  return {
    bindDomain: selectedDomain,
    appBaseUrl: applicationBaseUrl,
  };
}

// ========== [01] 初始化部署上下文 ==========
logPhase(1, "初始化部署上下文");

// 拉取主机详情（站点目录、端口、数据库信息、已绑定域名等）
var hostInfo = get_host_info({
  host_source: "custom",
  host_id: hostId,
});

if (!hostInfo || !hostInfo.host_name) {
  throw new Error("获取主机信息失败，host_name 为空");
}

// 拉取用户信息（邮件通知、本地域名绑定的 user_id 校验）
var userProfile = get_user_info({
  user_id: hostInfo.uid,
});

logInfo("主机: " + hostInfo.host_name + " | 用户: " + userProfile.username);

// 弹窗选择/输入域名，生成 appBaseUrl 供后续 config.yaml 与 Go 项目使用
var domainSelection = requestBindDomain(hostInfo);
var appBaseUrl = domainSelection.appBaseUrl;
var bindDomain = domainSelection.bindDomain;
var isExistingDomain = isDomainAlreadyBound(hostInfo, bindDomain);

if (isExistingDomain) {
  logInfo("域名策略: 复用已有绑定域名 → " + bindDomain);
} else {
  logInfo("域名策略: 绑定新域名 → " + bindDomain);
}

// 派生路径与运行时参数（均基于 host_name）
var siteRootPath = "/www/wwwroot/" + hostInfo.host_name;
var remotePackagePath = siteRootPath + "/" + packageFileName;
var binaryFilePath = siteRootPath + "/" + binaryFileName;
var configFilePath = siteRootPath + "/config/config.yaml";
var goProjectName = sanitizeGoProjectName(hostInfo.host_name);
var servicePort =
  hostInfo.port && hostInfo.port > 0 ? hostInfo.port : defaultPort;

logDetail("siteRootPath: " + siteRootPath);
logDetail("remotePackagePath: " + remotePackagePath);
logDetail("binaryFilePath: " + binaryFilePath);
logDetail("configFilePath: " + configFilePath);
logDetail("goProjectName: " + goProjectName + " | servicePort: " + servicePort);

// ========== [02] 检测并上传部署包 ==========
logPhase(2, "检测并上传部署包");

var packageExistsResult = check_file_exists({
  host_source: "custom",
  host_id: hostId,
  dirPath: siteRootPath,
  fileName: packageFileName,
  searchAll: false,
});

var uploadResult = null;
var packageUploaded = false;

if (packageExistsResult.found) {
  // 远程已有同名 zip → 跳过上传（幂等）
  logInfo("远程包已存在，跳过上传: " + packageFileName);
} else {
  logInfo("远程包不存在，开始上传: " + localPackagePath + " → " + packageFileName);

  uploadResult = upload_file({
    host_source: "custom",
    host_id: hostId,
    targetDir: siteRootPath,
    fileName: packageFileName,
    content_source: "local",
    content: localPackagePath,
  });

  if (!uploadResult || !uploadResult.status || uploadResult.progress !== 100) {
    throw new Error(
      "上传未完成: status=" +
      (uploadResult && uploadResult.status) +
      " progress=" +
      (uploadResult && uploadResult.progress),
    );
  }

  packageUploaded = true;
  logDetail("上传进度: " + uploadResult.progress + "%");
  logDetail("文件大小: " + uploadResult.file_size + " bytes");
  logDetail("远程路径: " + uploadResult.remote_path);

  // 上传完成后二次校验，防止静默失败
  var packageVerifyResult = check_file_exists({
    host_source: "custom",
    host_id: hostId,
    dirPath: siteRootPath,
    fileName: packageFileName,
    searchAll: false,
  });

  if (!packageVerifyResult.found) {
    throw new Error("上传后校验失败，远程未找到: " + packageFileName);
  }

  logInfo("部署包上传并校验通过");
}

// ========== [03] 解压并校验二进制 ==========
logPhase(3, "解压并校验二进制");

var binaryExistsResult = check_file_exists({
  host_source: "custom",
  host_id: hostId,
  dirPath: siteRootPath,
  fileName: binaryFileName,
  searchAll: false,
});

// 解压条件：二进制不存在，或刚上传了新包且配置了强制解压
var shouldExtractPackage = !binaryExistsResult.found || (packageUploaded && forceUnzipAfterUpload);

if (!shouldExtractPackage) {
  logInfo("二进制已存在且无需覆盖，跳过解压: " + binaryFileName);
} else {
  logInfo("开始解压: " + remotePackagePath + " → " + siteRootPath);

  unzip_files({
    host_source: "custom",
    host_id: hostId,
    zipPath: remotePackagePath,
    targetDir: siteRootPath,
    password: "",
  });

  logDetail("解压完成，开始校验二进制");

  var binaryVerifyResult = check_file_exists({
    host_source: "custom",
    host_id: hostId,
    dirPath: siteRootPath,
    fileName: binaryFileName,
    searchAll: false,
  });

  if (!binaryVerifyResult.found) {
    throw new Error("解压后未找到二进制: " + binaryFilePath);
  }

  logDetail("二进制校验通过: " + binaryFilePath);

  // Go 二进制需 www 用户可执行
  set_file_access({
    host_source: "custom",
    host_id: hostId,
    filename: binaryFilePath,
    user: "www",
    access: "755",
  });

  logInfo("二进制权限已设置为 755");
}

// ========== [04] 检查并初始化数据库 ==========
logPhase(4, "检查并初始化数据库");

var databaseName = sanitizeDbName(hostInfo.host_name);
var databaseUser = databaseName;
var databasePassword = hostInfo.db_password || "";
var databaseCreated = false;

logDetail("目标库名: " + databaseName);

var databaseCheckResult = database_exists({
  dbName: databaseName,
});

if (isDatabaseExists(databaseCheckResult)) {
  logInfo("数据库已存在，跳过创建: " + databaseName);

  // 库已存在时，优先使用主机记录里保存的真实连接信息
  if (hostInfo.db_name) {
    databaseName = hostInfo.db_name;
  }
  if (hostInfo.db_account) {
    databaseUser = hostInfo.db_account;
  }
  if (hostInfo.db_password) {
    databasePassword = hostInfo.db_password;
  }

  if (!databasePassword) {
    logDetail("警告: 数据库已存在但主机记录缺少 db_password，配置可能不完整");
  }
} else {
  // 新建库时若主机无密码记录，自动生成随机密码
  if (!databasePassword) {
    databasePassword = randomDbPassword(16);
  }

  logInfo("数据库不存在，开始创建: " + databaseName);

  var createDatabaseResult = create_database({
    dbName: databaseName,
    dbUser: databaseUser,
    dbPassword: databasePassword,
  });

  assertActionSuccess(createDatabaseResult, "create_database");

  var databaseVerifyResult = database_exists({
    dbName: databaseName,
  });

  if (!isDatabaseExists(databaseVerifyResult)) {
    throw new Error("创建数据库后校验失败: " + databaseName);
  }

  databaseCreated = true;
  logInfo("数据库创建成功: " + databaseName + " | 用户: " + databaseUser);
}

// ========== [05] 更新应用配置文件 ==========
logPhase(5, "更新应用配置文件");

// 小氢云商城 config.yaml 字段结构
var configReplacements = {
  "database.host": "127.0.0.1",
  "database.port": "3306",
  "database.username": databaseUser,
  "database.dbname": databaseName,
};

if (databasePassword) {
  configReplacements["database.password"] = databasePassword;
}

// 用户选定/输入的域名写入 app.base_url
configReplacements["app.base_url"] = appBaseUrl;
configReplacements["app.port"] = servicePort;

logDetail("目标文件: " + configFilePath);
logDetail("替换项: " + JSON.stringify(configReplacements));

var configinstallResult = replace_config_content({
  format: "yaml",
  host_id: hostId,
  filePath: configFilePath,
  replacements: configReplacements,
});

assertActionSuccess(configinstallResult, "replace_config_content");
logInfo("配置文件更新完成，修改项: " + JSON.stringify(configinstallResult.modified_keys));

// ========== [06] 检查并放行服务端口 ==========
logPhase(6, "检查并放行服务端口");

var portRuleCheckResult = port_rule_exists({
  port: servicePort,
});

if (portRuleCheckResult && portRuleCheckResult.exists) {
  logInfo("端口已放行，跳过: " + servicePort);
} else {
  logInfo("放行端口: " + servicePort);
  set_port_rule({
    port: servicePort,
    brief: "Go: " + hostInfo.host_name,
  });
  delay({ seconds: 2 });
  logDetail("端口规则写入完成，等待 2 秒生效");
}

// ========== [07] 注册并启动 Go 项目 ==========
logPhase(7, "注册并启动 Go 项目");

// 查重：避免重复 create_go_project
var matchedGoProject = findGoProject(goProjectName, hostInfo.host_name, siteRootPath);
var isGoProjectRegistered = !!matchedGoProject;
var goProjectDetail = matchedGoProject;
var activeProjectName = isGoProjectRegistered ?
  resolveGoProjectName(matchedGoProject) :
  goProjectName;
var goProjectCreated = false;

if (!isGoProjectRegistered) {
  logInfo("创建 Go 项目: " + goProjectName + " | 绑定域名: " + bindDomain);

  var createGoProjectResult = create_go_project({
    host_source: "custom",
    host_id: hostId,
    project_name: goProjectName,
    project_exe: binaryFilePath,
    project_cmd: binaryFilePath,
    project_ps: "Go: " + hostInfo.host_name,
    port: String(servicePort),
    path: siteRootPath,
    run_user: "www",
    release_firewall: false,
    is_power_on: true,
    domains: [bindDomain], // 宝塔侧绑定域名
  });

  assertActionSuccess(createGoProjectResult, "create_go_project");
  logDetail("create_go_project 响应: " + JSON.stringify(createGoProjectResult));

  goProjectDetail = verifyGoProjectExists(
    goProjectName,
    hostInfo.host_name,
    siteRootPath,
  );
  activeProjectName = resolveGoProjectName(goProjectDetail) || goProjectName;
  isGoProjectRegistered = true;
  goProjectCreated = true;
  logInfo("Go 项目创建并校验通过");
} else {
  logInfo("Go 项目已存在，跳过创建: " + activeProjectName);
}

// 本地系统绑定域名（lh_hosts.domains），与宝塔侧独立，后端自动去重
var localBindOutcome = bindDomainLocally(hostInfo, bindDomain);
var domainBoundLocally = localBindOutcome.domainBound;

var startGoProjectResult = start_go_project({
  projectName: activeProjectName,
});

if (!startGoProjectResult || startGoProjectResult.status !== true) {
  logInfo(
    "启动失败（" +
    activeProjectName +
    "），重新注册 Go 项目: " +
    goProjectName,
  );
  var recreateGoProjectResult = create_go_project({
    host_source: "custom",
    host_id: hostId,
    project_name: goProjectName,
    project_exe: binaryFilePath,
    project_cmd: binaryFilePath,
    project_ps: "Go: " + hostInfo.host_name,
    port: String(servicePort),
    path: siteRootPath,
    run_user: "www",
    release_firewall: false,
    is_power_on: true,
    domains: [bindDomain],
  });
  assertActionSuccess(recreateGoProjectResult, "create_go_project");
  goProjectDetail = verifyGoProjectExists(
    goProjectName,
    hostInfo.host_name,
    siteRootPath,
  );
  activeProjectName = resolveGoProjectName(goProjectDetail) || goProjectName;
  startGoProjectResult = start_go_project({
    projectName: activeProjectName,
  });
}

assertActionSuccess(startGoProjectResult, "start_go_project");
logDetail("start_go_project 响应: " + JSON.stringify(startGoProjectResult));
logInfo("Go 项目已启动: " + activeProjectName);

// ========== [08] 发送部署完成通知 ==========
logPhase(8, "发送部署完成通知");

var recipientEmail = userProfile.email || "";

// 邮件中域名状态文案
var domainStatusLabel = isExistingDomain ?
  "已有域名" :
  domainBoundLocally ?
  "新绑定" :
  "本地已存在/跳过";

if (recipientEmail) {
  send_email({
    to: recipientEmail,
    subject: "主机搭建通知 - " + hostInfo.host_name,
    body: "<p>主机 <strong>" +
      hostInfo.host_name +
      "</strong> 工作流执行完成。</p>" +
      "<ul>" +
      "<li>部署包: " +
      (packageExistsResult.found ? "已存在（跳过上传）" : "已上传") +
      "</li>" +
      "<li>二进制 " +
      binaryFileName +
      ": " +
      (binaryExistsResult.found && !shouldExtractPackage ?
        "已存在（未重新解压）" :
        "已解压/更新") +
      "</li>" +
      "<li>数据库: " +
      databaseName +
      (databaseCreated ? "（新建）" : "（已存在）") +
      "</li>" +
      "<li>站点域名: " +
      bindDomain +
      "（" +
      appBaseUrl +
      "，" +
      domainStatusLabel +
      "）" +
      "</li>" +
      "<li>配置文件: " +
      configFilePath +
      " 已更新</li>" +
      "<li>Go 项目: " +
      activeProjectName +
      "（端口 " +
      servicePort +
      "）</li>" +
      "<li>Go 项目状态: " +
      (isGoProjectRegistered ? "已注册并已启动" : "未注册") +
      "</li>" +
      "</ul>",
  });
  logInfo("通知邮件已发送至: " + recipientEmail);
} else {
  logInfo("用户未配置邮箱，跳过邮件通知");
}

logInfo("工作流全部步骤执行完成");

如何让用户使用他呢？

在基础设施->功能菜单里 可以添加自定义的菜单，然后绑定工作流

菜单会出现在用户后台的主机详情页面里

用户点一下就能执行了！

自定义节点函数

我给你们提供了一个查询宝塔应用商店插件的代码，可以参考一下

// ctx.params — 调用方传入的参数
// ctx.api_path / ctx.api_method / ctx.base_url / ctx.timeout_sec
// ctx.admin_token / ctx.user_token（按执行场景注入）

var resp = request({
  url: ctx.api_path,
  method: ctx.api_method || "POST",
  headers: { "Content-Type": "application/json" },
  body: ctx.params,
  timeout: ctx.timeout_sec || 30
});

return handle_response(resp, function(json) {
  if (json.http_status >= 400) {
    return { status: false, code: json.http_status, message: json.msg || "HTTP 请求失败" };
  }
  if (json.code !== undefined && json.code !== 200) {
    return { status: false, code: json.code, message: json.msg || "业务请求失败" };
  }

  var list = json.list;
  if (!list || !list.data) {
    return { status: false, code: -1, message: "接口返回缺少 list.data" };
  }

  var items = list.data;
  var pageHtml = String(list.page || "");
  var countMatch = pageHtml.match(/class=['"]Pcount['"]\s*>共(\d+)条/i);
  var totalCount = countMatch ? parseInt(countMatch[1], 10) : items.length;

  var names = [];
  for (var i = 0; i < items.length; i++) {
    var item = items[i] || {};
    var label = String(item.title || item.name || "").trim();
    if (label) {
      names.push(label);
    }
  }

  var summary;
  if (totalCount <= 0 || names.length === 0) {
    summary = "共查询到 0 个插件";
  } else {
    summary = "共查询到 " + totalCount + " 个插件，分别是：" + names.join("、");
  }

  return {
    status: true,
    code: 200,
    data: summary
  };
});

{
  "export_version": 1,
  "exported_at": "2026-05-25",
  "action": {
    "action_key": "get_soft_list",
    "name": "自定义节点 - 应用商店搜索",
    "category": "自定义的二级分类",
    "icon": "lucide:puzzle",
    "description": "筛选宝塔应用商店插件列表",
    "api_path": "/plugin?action=get_soft_list",
    "api_method": "POST",
    "params_schema": [
      {
        "key": "type",
        "type": "string",
        "label": "应用分类",
        "default": 0,
        "required": false,
        "default_type": "string",
        "accepted_types": [
          "string"
        ]
      },
      {
        "key": "query",
        "type": "string",
        "label": "筛选值",
        "required": true,
        "description": "搜索内容",
        "default_type": "string",
        "accepted_types": [
          "string"
        ]
      },
      {
        "key": "p",
        "type": "string",
        "label": "当前页",
        "default": 1,
        "required": false,
        "default_type": "string",
        "accepted_types": [
          "string"
        ]
      },
      {
        "key": "row",
        "type": "string",
        "label": "每页条数",
        "default": 15,
        "required": false,
        "default_type": "string",
        "accepted_types": [
          "string"
        ]
      },
      {
        "key": "force",
        "type": "string",
        "label": "",
        "default": 0,
        "required": false,
        "default_type": "string",
        "accepted_types": [
          "string"
        ]
      }
    ],
    "outputs_schema": [
      {
        "key": "status",
        "type": "bool",
        "label": "是否成功",
        "description": "true 表示成功；失败时为 false"
      },
      {
        "key": "code",
        "type": "int",
        "label": "状态码",
        "description": "成功为 200；HTTP/业务失败时为对应错误码"
      },
      {
        "key": "message",
        "type": "string",
        "label": "错误信息",
        "description": "status=false 时返回，如 HTTP 失败、缺少 list.data"
      },
      {
        "key": "data",
        "type": "object",
        "label": "业务数据",
        "description": "成功时对象，含 list 与 pagination"
      },
      {
        "key": "data.list",
        "type": "array",
        "label": "插件列表",
        "description": "应用商店条目数组（btwaf、bt_report 等）"
      },
      {
        "key": "data.pagination",
        "type": "object",
        "label": "分页信息",
        "description": "由 list.page HTML 解析得到"
      },
      {
        "key": "data.pagination.currentPage",
        "type": "int",
        "label": "当前页",
        "description": "对应当前页码，如 1"
      },
      {
        "key": "data.pagination.totalPages",
        "type": "int",
        "label": "总页数",
        "description": "如 1/1 中的 1"
      },
      {
        "key": "data.pagination.totalCount",
        "type": "int",
        "label": "总条数",
        "description": "如「共5条」中的 5"
      },
      {
        "key": "data.pagination.rangeFrom",
        "type": "int",
        "label": "本页起始序号",
        "description": "如「从1-5条」中的 1"
      },
      {
        "key": "data.pagination.rangeTo",
        "type": "int",
        "label": "本页结束序号",
        "description": "如「从1-5条」中的 5"
      },
      {
        "key": "data.pagination.pageHtml",
        "type": "string",
        "label": "分页原始HTML",
        "description": "宝塔返回的 list.page 原文"
      }
    ],
    "response_mapping": [],
    "script": "// ctx.params — 调用方传入的参数\n// ctx.api_path / ctx.api_method / ctx.base_url / ctx.timeout_sec\n// ctx.admin_token / ctx.user_token（按执行场景注入）\n\nvar resp = request({\n  url: ctx.api_path,\n  method: ctx.api_method || \"POST\",\n  headers: { \"Content-Type\": \"application/json\" },\n  body: ctx.params,\n  timeout: ctx.timeout_sec || 30\n});\n\nreturn handle_response(resp, function(json) {\n  if (json.http_status \u003e= 400) {\n    return { status: false, code: json.http_status, message: json.msg || \"HTTP 请求失败\" };\n  }\n  if (json.code !== undefined \u0026\u0026 json.code !== 200) {\n    return { status: false, code: json.code, message: json.msg || \"业务请求失败\" };\n  }\n\n  var list = json.list;\n  if (!list || !list.data) {\n    return { status: false, code: -1, message: \"接口返回缺少 list.data\" };\n  }\n\n  var items = list.data;\n  var pageHtml = String(list.page || \"\");\n  var countMatch = pageHtml.match(/class=['\"]Pcount['\"]\\s*\u003e共(\\d+)条/i);\n  var totalCount = countMatch ? parseInt(countMatch[1], 10) : items.length;\n\n  var names = [];\n  for (var i = 0; i \u003c items.length; i++) {\n    var item = items[i] || {};\n    var label = String(item.title || item.name || \"\").trim();\n    if (label) {\n      names.push(label);\n    }\n  }\n\n  var summary;\n  if (totalCount \u003c= 0 || names.length === 0) {\n    summary = \"共查询到 0 个插件\";\n  } else {\n    summary = \"共查询到 \" + totalCount + \" 个插件，分别是：\" + names.join(\"、\");\n  }\n\n  return {\n    status: true,\n    code: 200,\n    data: summary\n  };\n});",
    "timeout_sec": 30,
    "status": 1,
    "sort": 0,
    "scope": "admin",
    "allow_external_url": 1
  }
}

直接复制这段 JSON 保存到

然后在工作流的这里就能看到和使用了

效果：

如果你还有想调用查询本地 SQL 的需求，有的有的

我加了执行 SQL 的节点函数，支持增删改查，有 SQL 注入攻击防护，支持执行多行 SQL。

正式测试

先创建一个 Go 类型的主机

试一下一键部署！

带有实时进度！

完美了！

剩下的就靠你们自己发挥创造力了！

后面会更新一个脚本商店的功能，有可能实现站长盈利！

新增授权密钥弹窗增加节点切换下拉框，可在填写密钥前切换授权节点

新增幸运抽奖功能（大转盘）

新增管理后台-抽奖活动管理（活动CRUD、奖品配置、中奖记录）

新增用户中心-幸运抽奖页面（大转盘抽奖、中奖记录）

新增实物奖品发货流程（用户领取→待发货→管理员发货→已发货+物流信息）

新增抽奖活动管理页增加「说明」按钮和使用教程弹窗

新增抽奖奖品新增「商品兑换卡」类型（自动生成卡密+中奖弹窗显示+复制）

新增管理后台-系统设置增加卡密生成权限价格配置项

新增用户中心-卡密生成权限购买增加价格显示和确认对话框

新增后台新增 /api/admin/updateUserPermissions 独立接口（不校验密码）

新增商品编辑增加「活动余额下单」开关

新增活动余额支付功能（PaymentWay返回选项+下单接口支持）

新增PC端商品详情-立即购买传pt参数到PaymentWay

新增PE端首页购买流程从旧main.php切到新/api/PaymentWay接口并传pt参数

新增后台管理-文件管理解压增加弹窗交互（目录浏览器选择、输入解压密码）

新增文件管理-目录大小列增加"计算"按钮可统计目录内文件总大小

新增后台管理-文件管理增加压缩功能（可选择ZIP/TAR.GZ/TAR格式、设置密码、自定义文件名）

新增管理后台API调用助手脚本（admin_api.sh / get_admin_token.sh）

修复用户中心-/api/getUserInfo 缺少 OptionalAuth 中间件导致 token 未解析、前端误判为未登录清空 token

修复修复 GetSubstationConfig 未返回 card_create_price 导致用户端始终显示免费

修复新订单消息盒子里「下单用户」显示游客问题修复（已登录用户自动补全用户名）

优化PE/PC 订单详情页渲染 custom_content（供应商订单进度自定义数据）

优化用户管理-卡密生成权限从编辑表单独立为表格开关列

优化用户管理-操作菜单编辑按钮补全缺失的图标

优化管理后台-编辑用户密码不再必填，留空则不修改

优化路由管理-解压文件弹窗增加密码输入和目录选择功能

优化文件管理器增加拖拽框选功能（卡片和列表视图均支持）

优化文件管理-列表/卡片切换使用 v-show 保留 DOM 状态避免重建

优化文件管理-解压时目标目录/文件冲突自动追加" - 副本"重命名避免覆盖

优化features/cloud_config缓存TTL与license缓存保持一致，防止features提前过期导致功能误判（主机系统"未授权"）

小氢云广告投放系统

演示站地址：https://demo-ad.ithxs.com

小氢云授权系统

https://demo-auth.ithxs.com

小氢云商城系统

https://demo-xqy.ithxs.com

小氢云护航系统

https://demo-game.ithxs.com

小氢云发卡系统

https://demo-faka.ithxs.com

小氢云支付宝中台

待添加

小氢云系统分析系统

待添加

小氢云聚合 API 系统

待添加

小氢云导航系统

https://demo-saas.ithxs.com

新增功能- 用户端「我的订单」游客查单模式：增加信息解码按钮与弹窗，封装 guestOrderReveal，解码后合并列表与详情中的下单信息与卡密（与 PC端行为一致）。

• 管理后台系统设置 -通知推送 -语音通知：支持按交单状态多选、自定义 MP3上传（地址栏内置上传功能）；消息中心订单推送携带 order_code并按配置播放；image_up支持上传 MP3并存入 static/media目录。

• 订单详情类接口新增 custom_content字段：包含 label与 value，数据源为订单 data.custom_content；涉及接口：/api/getOrderDetail、/api/queryOrder、/api/orderByKey。游客模式下，对敏感字段（value、tokens、redeem_links、备注发卡段）脱敏逻辑保持一致，并受 order_flow_display控制进度展示；PC与 PE端未登录订单页统一支持信息解码与回显；PE端订单列表与详情页未登录及查单同样支持信息解码；normalizeQueryOrderItem补充 uid字段。

• 管理后台操作密钥（security.admin_operation_key / SECURITY_ADMIN_OPERATION_KEY）：支持通过请求头 X-Admin-Operation-Key或查询参数 admin_operation_key传递。密钥与配置一致时，等同主管理员 JWT，可访问需鉴权的接口，并绕过云端授权、免责声明与数据库安全口令限制；config.yaml新增示例配置项。

• 数据库安全相关接口与页面（数据迁移、备份、管理）：引入独立安全口令（sky_config中存储 bcrypt加密值），首次进入后台强制设置，修改需提供旧密码；签发短时 JWT（30分钟有效，通过 X-Database-Safe-Token传递）；未验证接口返回 code=94001，前端弹窗提示解锁；安全口令表单 maxlength绑定数字类型，消除类型告警；Verify/set-password接口支持主站管理员 JWT（UserID=0）下的口令判定及短时 token返回；DatabaseSafeGate组件修复首次设置表单未绑定模型与 @finish问题。

• 后台商品编辑新增“每份发货数量” (delivery_quantity)：当 price_precision不在2~8有效范围内时，按售价字符串自动推断精度（管理员与供货商共用逻辑）。

• 后台卡密批量导入支持“去重添加”：弹窗与后端 batchImport逻辑保持一致，在同一商品、同一规格的本次导入批次内自动去重。

• 游客查单密码功能：下单/详情页支持选填密码，密码使用 bcrypt存储，接口校验后完整回显。

问题修复- 管理端本机语音提醒：修复首次点击页面或消息铃铛时，未能解锁音频以符合浏览器自动播放策略的问题；捕获 NotAllowedError异常时，对用户进行一次提示。

• 卡易信货源下单：修复订单即时返回的卡密仅存卡号与卡密拼接，未包含上游 cardId的问题。

• 系统任务价格监控：修复支持范围，现在一并兼容网课货源（wk=1，不再排除 aid）。

• CORS预检：修复对 X-Database-Safe-Token头部的放行问题，避免浏览器拦截携带数据库安全口令的请求。

• 订单页与游客订单页样式：修复搜索条样式相互干扰的问题；查单解码密码框样式修正。

• 信息解码弹窗：修复 zIndex层级问题；详情页 .page的 overflow-x样式裁剪弹层问题。

• 订单详情与列表页文案：修复卡密、解码、收货优先级、按钮样式与顺序等底部文案的统一性问题。

• 订单详情页布局：修复购买与价格信息并入信息卡片后的位置优化；卡密区宽度盒模型修正；订单进度条移至卡密区块下方。

• 订单详情金额显示：修复人民币金额、单价、规格切换等所有金额字段均需按照 price_precision进行舍入的问题。

• 商品详情网课查课按钮：修复逻辑优化，接口 loading状态优先使用 inject goodsDetailPage。

• 计划任务日志清理：修复任务逻辑，现在可同时清理磁盘日志；数据库表名统一为 background_process_log，前端新增清理选项。

• “查看错误”按钮展示逻辑：修复仅在交单失败且 code=2时展示，避免 code=3被误判。

• PC端商品详情页：修复隐藏参数及校验下标不一致的问题，避免已填写项被误报。

• 嵌入静态支付成功页：修复商品名去除富文本标签后展示，仅保留纯文本内容。

功能优化- 管理端本机语音提醒：开启且未填写 MP3地址时，默认使用内置 /static/tongzhi.mp3文件；Vite开发环境代理 /static路径至后端。

• 本机语音提醒并发播放：优化对短时间内多条 WebSocket订单消息的处理，使用独立 Audio实例并发播放（避免单路互相打断），并发上限为16个。

• 系统设置 -通知推送：优化管理端本机语音提醒的独立分区展示，与「通知渠道（服务端推送）」的说明进行区分；配置项文案同步优化区分。

• 管理员后台在线客服列表页：修复左面板点选联系人后，未能清除 URL中残留的 ?contactId参数的问题（该参数会导致30s轮询 fetchList时页面回跳或头部弹窗导航意外切换会话）；selectContact逻辑中新增清除 URL contactId的处理；fetchList中类型比较改用 String()，避免类型不一致导致 selectedContact被误清空；URL自动选择逻辑增加 !selectedContact.value防护。

• PC端装修/首页促销/砍价秒杀等区块：无数据时不渲染，提升页面性能；AGENTS说明全局规则使用分文件管理。

• 用户端订单列表及详情接口：优化单选/下拉下单信息的展示，现在显示选项标签，不再显示 value。

• 用户端兑换卡密页：优化支持说明折叠，未开通状态有相应提示。

安装 nats

使用宝塔 Docker ，找到 Docker 中的容器，创建容器，使用命令创建，输入下面命令 ：

# 创建持久化目录
mkdir -p /www/server/nats/jetstream

# 正式部署推荐命令
docker run -d \
  --name jitong-nats \
  --restart unless-stopped \
  -p 4222:4222 \
  -p 8222:8222 \
  -v /www/server/nats/jetstream:/data/jetstream \
  nats:latest \
  -js -sd /data/jetstream

端口号可以根据自己的需要更改，改后面的，冒号后面的！

安装 PostgreSQL

继续安装，找到宝塔的应用商店，找到 PostgreSQL 管理器，安装插件，打开插件安装最新版的PostgreSQL 即可。

连接你的数据库，使用

ALTER USER your_app_user WITH SUPERUSER 命令把你创建的数据库用户改成超级用户，否则用不了！

安装 clickhouse

再在Docker中安装 clickhouse 直接搜就行

安装后打开宝塔终端

执行以下命令

1️⃣ 进入 ClickHouse 容器

docker exec -it 你的容器名 bash

2️⃣ 创建一个新的用户配置文件

在 /etc/clickhouse-server/users.d/ 目录下新建一个 jitong.xml：

bash

cat > /etc/clickhouse-server/users.d/jitong.xml << 'EOF'
<yandex>
    <users>
        <jitong>
            <password>你的密码</password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
        </jitong>
    </users>
</yandex>
EOF

说明：

• password 标签内是明文密码 **********（你也可以用 <password_sha256_hex> 加 hash，但明文简单）。

• <ip>::/0</ip> 表示允许任何 IP 连接，按需可改成具体 IP 段。

• profile 和 quota 使用默认值。

3️⃣ 退出容器并重启 ClickHouse

exit

重启容器

docker restart 容器名

4️⃣ 验证用户是否创建成功

docker exec 容器名 clickhouse-client -u jitong --password 你的密码 -q "SELECT 1"

如果返回 1，说明用户创建成功且密码正确。

注意

使用 Docker 安装的话配置文件里填写的地址就尽量填写 Docker 的内网地址，如：172.17.0.3

建议使用 Docker 内网地址！

其他

剩下的安装和商城逻辑一样！

事情起因是这样，群里有一些人整天发广告，就撤回+禁言套餐了，刚好有这个人，一直发消息问为啥禁言他，看这架势就懒得回 没理他，不知道是不是破防了就开始喷了，小学生行为懒得理，最近更是放肆了，到处发抹黑消息😂

估计不少人被这狗咬过

下面是截图：

😂

真的不想回这种问题