部署助手详解

更新时间：2026/8/18 23:50:21

本页是 DaxPay 部署助手的完整操作手册，覆盖安装原理、命令行管理、向导六步详解、日常运维、配置细节与故障排查。想跟着向导快速走一遍部署流程，请先看一键部署。

部署助手是一个单 Go 二进制（go:embed 内嵌 Vue 前端），提供两种工作模式：

部署引导：面向首次部署的线性向导，六步顺序推进，步骤状态实时联动
运维管理：面向日常变更的无序运维，包含总览、基础环境、业务环境、网关管理、Docker 管理、数据存储、操作审计、全局配置八个页面

顶部可切换两种模式。所有耗时操作（安装、部署、构建、证书签发等）统一走异步任务，右下角输出终端 SSE 实时回显，任务持久化到磁盘，刷新页面可恢复历史日志，支持手动取消。

安装原理

在线安装

在线安装通过一行命令把脚本管道给 bash 执行：

bash

curl -fsSL https://download.daxpay.top/open/script/install.sh | sudo bash

脚本内部使用了两个相互独立的下载源（是 SHA256 防投毒的前提）：

源	默认地址	用途	覆盖方式
二进制源	`https://download.daxpay.top/open/install`	下载 `.xz` 程序压缩包	环境变量 `DAXPAY_MIRROR` 或 `--mirror`
脚本源	`https://download.daxpay.top/open/script`	管道模式下脚本落盘自身	环境变量 `SCRIPT_MIRROR`

安装流程：探测环境（架构 / 发行版 / 磁盘 / xz）→ 下载压缩包到临时目录 → SHA256 强制校验（期望哈希硬编码在脚本顶部，由发版工具回填）→ xz 解压 → ELF 格式兜底校验 → 安装到 /opt/daxpay → 建立 daxpay 软链 → 可选 systemd 服务 → 启动面板。

SHA256 强制校验

校验失败脚本会直接终止，没有逃生口。失败提示三种可能：下载损坏、install.sh 过期、镜像源异常。换源可用 DAXPAY_MIRROR=<url> curl ... | sudo bash，或离线安装。

幂等行为：检测到已安装且未加 --force 时，会弹出交互菜单（跳过 / 重新下载升级 / 退出）。--yes 跳过询问。升级时旧二进制自动备份为 <二进制>.bak，可回滚。

离线安装

离线安装只需两个文件，全程不联网：

文件	说明
`install.sh`	安装与管理脚本，当前版本的 SHA256 已回填其中
`dax-pay-installer-linux-amd64.xz`	程序压缩包（约 15 MB）

工作原理：脚本启动后，find_local_package 只探测脚本自身所在目录是否含有 .xz 包（不探测当前工作目录 $PWD，避免装完后在离线目录里误判）。探测到则复制到临时目录，后续的校验、解压、安装与在线安装完全共用同一条链路。curl | bash 管道模式会跳过离线探测，恒走在线。

chmod 授权（重点）：脚本与压缩包的授权要求不同。

bash

# 方式一：直接用 bash 调用 install.sh —— 无需 chmod 授权
sudo bash install.sh

# 方式二：把 install.sh 作为可执行程序运行 —— 需要先 chmod 授权
chmod +x install.sh
sudo ./install.sh

install.sh：bash install.sh 不需要授权；./install.sh 必须先 chmod +x install.sh
dax-pay-installer-linux-amd64.xz：无需授权，脚本用 xz 解压它，不是直接执行

离线包必须同目录

两个文件必须放在同一个目录里，脚本只探测自身所在目录。压缩包放到别的目录（包括 $PWD）不会被识别，会回退到在线下载或显示帮助。

系统要求

项目	要求	说明
架构	x86_64（amd64）	arm64 会被直接拒绝并退出
操作系统	ubuntu / debian / centos / rocky / rhel / almalinux / fedora	不在列表的发行版仅警告，不阻断
磁盘	安装目录所在分区 ≥ 500 MB	低于阈值仅警告
依赖：xz	必需	缺失时自动按发行版安装（`dnf` / `yum` / `apt` / `apk`），统一 10 分钟超时
依赖：curl	在线安装必需	脚本不自动安装
依赖：sha256sum	校验必需	缺失报错并给出安装命令
权限	root 或 sudo	非 root 会自动 `sudo` 重跑；`curl

xz 自动安装失败怎么办

自动安装 xz 多因软件源访问慢超时（RHEL / Oracle 官方源常见）。超时后脚本会按发行版给出手动安装命令，例如 dnf install -y xz 或 apt-get install -y xz-utils，手动执行后重跑安装即可。

systemd 与 daemon 托管

部署助手可以由 systemd 托管（开机自启 + 崩溃自动拉起），也可以 daemon 模式后台运行。

如何判定：脚本同时满足两个条件才认为 systemd 可用——/run/systemd/system 目录存在，且 PID 1 进程名为 systemd（防止 WSL 半启动 / 容器残留目录误判）。

模式	systemd 可用	systemd 不可用（容器 / WSL）
开机自启	支持	不支持（警告提示）
崩溃自动拉起	`Restart=on-failure`	不支持
启动方式	`systemctl start daxpay-panel`	二进制 `setsid` 后台运行
端口	恒 8060（unit 不传 `--port`）	可用 `--port` 自定义
日志	`journalctl -u daxpay-panel`	`<workdir>/logs/installer-stdout.log`

安装时若 systemd 可用，会询问「是否生成 systemd 服务」；--yes 默认生成。systemd 服务单元位于 /etc/systemd/system/daxpay-panel.service，服务名沿用 daxpay-panel。

升级与卸载

升级：加 --force 强制重新下载覆盖，旧版本备份为 .bak。

bash

# 在线升级
curl -fsSL https://download.daxpay.top/open/script/install.sh | sudo bash -s -- install --force
# 离线升级（用新的两个文件覆盖）
sudo bash install.sh --force

卸载：

bash

daxpay uninstall            # 默认：只删面板程序，保留工作目录与数据
daxpay uninstall --purge    # 彻底清理：连工作目录 /opt/daxpay 一起删（需两道确认）

卸载不清理业务容器

uninstall 只移除面板自身（二进制 / 脚本 / 软链 / systemd 单元），不停止也不清理已部署的 DaxPay 业务容器。彻底清理业务需要手动执行：

bash

cd /opt/daxpay
docker compose -f docker-compose.biz.yml down -v
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.gateway.yml down -v

命令行参考

在线安装后用 daxpay 命令管理（已建软链 /usr/local/bin/daxpay）；也可直接调用二进制 dax-pay-installer <子命令>。

子命令

命令	说明
`daxpay status`	查看运行状态（PID / 端口 / 鉴权模式）
`daxpay start`	后台启动（可透传 `--no-auth` / `--port=N`）
`daxpay stop`	停止（systemd 走 systemctl，否则读 PID 文件发信号）
`daxpay restart`	重启（读 `/proc` 保留原启动参数，如端口 / `--no-auth`）
`daxpay logs -f`	实时跟随日志；`--installer` 切应用访问日志 `installer.log`
`daxpay info`	打印访问地址、实际端口与初始管理员凭据
`daxpay unlock`	登录失败连续 5 次被锁定时解锁（清零失败计数）
`daxpay reset-password`	重置面板密码（`--username/--password` 可非交互，同时解锁并吊销会话）
`daxpay uninstall`	卸载（`--purge` 彻底清理，详见上文）
`daxpay help`	完整帮助

常用安装选项

选项	说明
`--force`	强制重新下载覆盖（升级）
`--yes` / `-y`	跳过交互确认，用默认（CI 友好）
`--mirror <url>`	覆盖二进制下载源（或设环境变量 `DAXPAY_MIRROR`）
`--workdir <dir>`	覆盖工作目录（默认 `/opt/daxpay`；安装/卸载/管理命令均可用。管理命令按管理脚本所在目录自动识别安装目录，自定义目录安装后通常无需显式传入）
`--no-auth`	关闭访问鉴权（启动 flag，仅本地测试用，不入 state，切勿用于公网）

安装目录结构

工作目录默认 /opt/daxpay，运行后生成：

/opt/daxpay/
├── installer-state.json           面板状态（账号凭据 / 全局配置 / 部署快照）
├── installer.db                   操作审计日志（SQLite）
├── installer-initial-password.txt 首次启动生成的初始管理员凭据
├── dax-pay-installer              二进制本体
├── install.sh                     管理脚本（daxpay 软链目标）
├── docker-compose.yml             基础环境（PostgreSQL / Redis / Artemis）
├── .env                           基础环境凭据（随机密码）
├── docker-compose.biz.yml         业务系统（后端 / 通道子应用 / 三前端）
├── .env.biz                       业务系统配置与凭据
├── docker-compose.gateway.yml     网关（nginx）
├── .env.gateway                   网关配置
├── logs/
│   ├── installer.log              应用访问日志（gin，按大小滚动）
│   └── installer-stdout.log       后台模式 stdout（启动 banner + 初始密码）
└── data/                          bind mount 数据卷（停止/删除容器不清空）
    ├── postgresql/ redis/ artemis/   基础环境数据
    ├── biz/                       业务数据（含 runtime-conf/runtime.env）
    └── nginx/                     网关配置 / 证书 / 日志

向导六步详解

「部署引导」模式按六步顺序推进，顶部步骤导航实时反映每步完成状态。下面是每一步的选项含义、原理与注意点。

第 1 步：环境检查

确认部署的前置条件。

Docker / Git：未安装时点击「安装 Docker」/「安装 Git」，面板基于 linuxmirrors.cn 脚本一键安装（国内源 + 镜像加速器，实时日志回显）
项目代码：点击「下载代码」拉取 DaxPay 全部仓库源码（默认 Gitee：dromara/dax-pay、opendaxpay/dax-pay-channel-one、dax-pay-ui、dax-pay-h5）
系统环境：查看宿主机内存、CPU、端口冲突情况

已有 Docker 可跳过

若服务器已经装好 Docker，直接进入下一步即可。Git 仅在需要从源码构建镜像时必需。

第 2 步：全局配置

设置贯穿构建与部署的全局参数。

内存档位：紧凑 / 标准 / 增强，点击「应用档位」会批量下发到基础环境、业务、网关三套 stack 的 mem_limit，并联动 JVM 类型（紧凑档默认 OpenJ9）。详见配置详解 - 内存档位
运行形态：JVM 选 HotSpot 或 OpenJ9；通道子应用选 Java 版或 Go 版（选 Go 版会禁用 Java 通道，GO_CHANNEL_ENABLED=false）
部署版本：选 4.0 分支或某个 Release Tag（Tag 列表由各仓库共有 Tag 动态拉取）。切换版本后需回到第 1 步点「更新源码」
构建加速源：Maven / npm / Go 预设国内源或自定义，加快镜像构建

应用档位后需重新部署

应用内存档位只改配置，需要对三套 stack 重新部署才生效。页面会出现 drift 横幅提示「重新部署」。

第 3 步：镜像构建

把源码构建成 Docker 镜像。

IP 数据文件（ip2region）：主应用审计日志的 IP 归属功能依赖 v4 与 v6 两个 .xdb 文件，这是后端镜像构建的前置条件。v4 可一键从加速源下载，v6 需打开下载页手动下载或上传 .xdb
一键构建全部：串行构建主后端 → 通道子应用 → 运营端 → 商户端 → H5 五个镜像，首次约 30-60 分钟
单服务构建：每个服务卡片可单独构建 / 重建，方便排错

为什么 IP 文件是前置

后端 Dockerfile 在构建时 COPY 这两个 .xdb 文件并校验，缺失则构建失败。文件位于 data/ip/ 目录。

第 4 步：基础环境

部署三个基础中间件。

点击「部署基础环境」，一键完成：校验 Docker → 渲染 .env 与 compose → 建数据目录 → 拉镜像 → 启动 PostgreSQL / Redis / Artemis
凭据：中间件密码自动生成，可在「凭据与连接」查看（结构化、打码可切换、一键复制）
一键改密：需要修改密码时，面板在容器内执行改密命令 → 同步配置 → 重启业务容器，全链路自动

改密后业务自动生效

中间件密码迁移到 runtime.env 后，改密重启业务容器即生效，无需重建镜像或手动改配置文件。

第 5 步：服务部署

部署 DaxPay 业务系统。

5.1 数据库初始化：执行 table.sql（表结构）+ data.sql（初始数据），可勾选「强制重建」
5.2 一键部署：三件套门控——「镜像已构建 + 数据库已初始化 + IP 文件就绪」齐备后部署按钮才解锁。点击后：校验三个中间件运行 → 补齐业务密钥（RSA / AES / 通道传输密钥，只在首次部署生成一次）→ 渲染 .env.biz 与 compose → 启动容器 → 回写部署快照

业务密钥只生成一次

RSA 私钥/公钥、AES 加密钥、通道传输密钥在首次部署时自动生成并固化。重新生成会导致已加密的数据无法解密，生产环境请谨慎。

第 6 步：网关接入

部署统一网关并对外提供服务。

部署网关：拉起独立 nginx 网关容器（external join 基础网络 daxpay-base_default，前置：基础环境已部署）
绑定域名：运营端 / 商户端 / H5 / 后端 API / Artemis 控制台共 5 个目标，填裸域名（禁 http:// 前缀），留空不绑定。绑定前端域名后，该前端容器端口会收敛到 127.0.0.1 只让网关访问
配置 HTTPS：三种模式
- auto：ACME 自动签发（lego v5，HTTP-01 验证，自动续期）
- manual：为每个域名上传 fullchain.pem + privkey.pem
- off：仅 HTTP（明文，生产不推荐）
- 有证书时 nginx 自动生成 443 ssl + http2，80 自动 301 跳 HTTPS
对外接口（零信任，默认全关）：按需开启 /unipay（商户开放 API）、/epay（易支付兼容）、/unipay/callback（通道回调）；/admin/、/mch/、/swagger-ui/ 等管理路径恒 404 封禁
应用配置：改动即时保存（置 Dirty），点击「应用网关配置」渲染 nginx 配置并 reload 生效

drift 横幅

网关配置改动未应用时，页面横幅提示「应用网关配置」；若仅全局配置（如内存档位）变更，则提示「重新部署」重建容器。两者不要混淆。

运维管理

顶部切换到「运维管理」模式，按需操作八个页面。

总览

系统信息、实时负载（CPU / 内存 / 磁盘 / 平均负载，10 秒轮询）、基础环境与业务服务状态卡片、端口冲突一览。点击卡片可带 focus 参数跳转到对应管理页并高亮定位。

基础环境

PostgreSQL / Redis / Artemis 三个中间件的统一服务卡片：启动 / 停止 / 重启 / 重新部署 / 删除容器 / 查看日志 / 详情 / 配置。整组操作有一键部署、启动全部、停止全部、重启全部。「查看密码」弹窗与一键改密。支持卸载（保留数据卷）。

业务环境

上半（运行态）：后端组（主应用 / 通道子应用）与前端组（运营 / 商户 / H5）分组启停 / 重启、单服务部署 / 重部署 / 删容器、应用配置抽屉、密钥管理抽屉、通道子应用信息抽屉
下半（版本与构建）：项目代码下载 / 更新 / 检查更新、部署版本切换（branch / tag）、数据准备（DB 初始化 + IP 文件）、镜像构建（一键构建全部）
顶部 drift 横幅、版本漂移提示、当前运行版本摘要

网关管理

域名绑定、HTTPS 证书、对外接口开关、网关日志查看、网关生命周期（一键部署 / 重新部署 / 启停 / 重启 / 卸载，保留数据卷与证书）。

Docker 管理

配置（引擎信息 / 镜像加速器在线切换，写 daemon.json + 重启 Docker）、容器（列表 + 搜索 + 启停 + 日志 + 详情 + 磁盘明细）、镜像（列表 + 删除 + 清理悬空）、网络，资源占用实时轮询。

数据存储

宿主机磁盘与 data/ 数据目录的只读统计（用途分类、大小、文件数），bind mount 数据卷落盘说明。纯只读页面，清理操作请到 Docker 管理。

操作审计

所有写操作（部署 / 构建 / 启停 / 配置更新 / 登录等）自动留痕到 SQLite，按功能域 / 动作 / 对象 / 结果多维筛选，支持详情与原始 JSON 查看。

全局配置

内存档位、运行形态、构建加速源的日常入口（与向导第 2 步同源双入口）。变更后按 drift 横幅提示重新部署生效。

配置详解

内存档位

三个预设档位，应用后会批量下发到三套 stack 的 mem_limit，并联动 JVM 类型。

档位	推荐宿主内存	合计占用	JVM 默认	说明
紧凑 compact	≥ 4 GB	约 3.1 GB	OpenJ9	最低配服务器
标准 standard（推荐）	≥ 8 GB	约 6.3 GB	HotSpot	生产常规配置
增强 enhanced	≥ 16 GB	约 12.9 GB	HotSpot	生产高并发

自动推荐与容差

面板根据宿主机内存自动推荐档位，并带 512 MB 容差（标称 4 GB 的云主机实际往往只有 3.6-3.8 GB，容差避免误拦）。低于有效下限（约 3.5 GB）前端拦截且后端拒绝部署。

应用档位只改配置，需要对三套 stack 重新部署才生效（drift 横幅会提示）。单服务微调 mem_limit 或运行时配置后，会自动标记为「自定义」档，应用预设档可恢复。

运行时配置 runtime.env

文件位于 <workdir>/data/biz/runtime-conf/runtime.env，backend 与通道子应用共享挂载，容器启动时 source 进进程环境。

配置项	说明
`DEPLOY_MODE`	部署模式：DEV（联调，放开沙箱 / 超管）/ PROD（生产，强制关沙箱 / 超管，fail-fast）
`SANDBOX_ENABLED`	沙箱开关（仅 DEV 有效）
`ENABLE_ADMIN`	超管默认开启（仅 DEV 有效，PROD 强制关闭）
`TRADE_SYNC_ENABLED`	交易同步（生产建议开启）
`LOG_ROOT_LEVEL`	日志级别：INFO / WARN / DEBUG

此外还包含三个中间件密码（DB_PASSWORD / REDIS_PASSWORD / ARTEMIS_PASSWORD）。

改后 restart 即生效

运行时配置修改后，重启业务容器即生效，无需重建容器或镜像。前端管理入口：运维管理 → 业务环境 → 主应用卡片 → 应用配置。

域名与 HTTPS

网关支持 5 个域名绑定目标：

目标	说明
ui-admin	运营管理端
ui-merchant	商户端
h5	H5 端
backend	后端 API
artemis	Artemis 控制台（走 8161 端口，含 WebSocket 升级头）

只填裸域名（禁 http:// 前缀），留空不绑定。HTTPS 三种模式：auto（ACME 自动签发 + 自动续期）、manual（上传证书）、off（仅 HTTP）。有证书时 nginx 生成 443 ssl + http2，80 自动 301 跳 HTTPS。

对外接口零信任

后端接口默认全部不对外暴露，需在「网关管理 → 对外接口」按需开启：

路径前缀	用途
`/unipay`	商户开放 API
`/epay`	易支付兼容 API
`/unipay/callback`	通道回调

另有「一键开启全部」便于联调。/admin/、/mch/、/demo/、/test/、/swagger-ui/ 等管理端路径恒 404 封禁，管理端登录态接口只走前端域名的 /api/ 转发。

故障排查

安装阶段

在线下载失败 / 校验不通过

可能是下载源异常或 install.sh 过期。换源重试：

bash

DAXPAY_MIRROR=<你的镜像站> curl -fsSL https://download.daxpay.top/open/script/install.sh | sudo bash

或改用离线安装。

xz 缺失导致安装中断

脚本会自动安装 xz，若因软件源慢超时失败，按提示手动安装后重跑：

bash

# RHEL 系
dnf install -y xz
# Debian 系
apt-get install -y xz-utils

离线安装没反应 / 提示在线下载

确认 install.sh 与 .xz 两个文件在同一个目录（脚本只探测自身所在目录，不探测 $PWD）。确认用 bash install.sh 或 chmod +x && ./install.sh 执行。

登录阶段

忘记初始密码

bash

daxpay info              # 查看初始账号密码
cat /opt/daxpay/installer-initial-password.txt   # 或直接看文件

若已改过密码又忘了，重置：

bash

daxpay reset-password    # 交互式重置（同时解锁并吊销其他会话）

登录失败被锁定

连续 5 次输错密码会锁定，CLI 解锁：

bash

daxpay unlock

运行阶段

端口冲突（8060 / 80 / 443）

8060 是面板端口，80 / 443 是网关端口。若被占用，停掉占用进程或用 --port 换面板端口（daemon 模式）。总览页会列出端口冲突。

业务后端 unhealthy（反复重启）

常见根因是数据库密码为空——.env.biz 注入了空的 DB_PASSWORD，导致认证失败反复重启。在基础环境「凭据与连接」确认密码非空，必要时一键改密后重新部署业务容器。

页面出现 drift 横幅

提示「重新部署」：全局配置（如内存档位）变更未生效，需重建对应容器
提示「应用网关配置」：网关配置改动未应用，点击应用即可（nginx reload，无需重建容器）

已部署但面板显示「未部署」

「已部署」判定基于运行时容器探测 + 部署快照一致。若手动用 docker compose 拉起容器（没写快照），面板启动时会自动按当前状态补齐快照自愈。若仍未识别，到对应页面点一次「部署」让面板接管。

下一步

一键部署：跟着向导快速走一遍部署流程
配置说明：各应用 Profile、端口、数据库、密钥与生产环境变量
Docker 部署：手动 docker-compose 编排模板（二次开发参考）

部署助手详解 ​

安装原理 ​

在线安装 ​

离线安装 ​

系统要求 ​

systemd 与 daemon 托管 ​

升级与卸载 ​

命令行参考 ​

子命令 ​

常用安装选项 ​

安装目录结构 ​

向导六步详解 ​

第 1 步：环境检查 ​

第 2 步：全局配置 ​

第 3 步：镜像构建 ​

第 4 步：基础环境 ​

第 5 步：服务部署 ​

第 6 步：网关接入 ​

运维管理 ​

总览 ​

基础环境 ​

业务环境 ​

网关管理 ​

Docker 管理 ​

数据存储 ​

操作审计 ​

全局配置 ​

配置详解 ​

内存档位 ​

运行时配置 runtime.env ​

域名与 HTTPS ​

对外接口零信任 ​

故障排查 ​

安装阶段 ​

登录阶段 ​

运行阶段 ​

下一步 ​

部署助手详解

安装原理

在线安装

离线安装

系统要求

systemd 与 daemon 托管

升级与卸载

命令行参考

子命令

常用安装选项

安装目录结构

向导六步详解

第 1 步：环境检查

第 2 步：全局配置

第 3 步：镜像构建

第 4 步：基础环境

第 5 步：服务部署

第 6 步：网关接入

运维管理

总览

基础环境

业务环境

网关管理

Docker 管理

数据存储

操作审计

全局配置

配置详解

内存档位

运行时配置 runtime.env

域名与 HTTPS

对外接口零信任

故障排查

安装阶段

登录阶段

运行阶段

下一步