安装教程

站长支付安装在一台 Linux 服务器上。本页按宝塔面板讲：nginx、MySQL、Redis 都用宝塔安装和管理，按下面的顺序操作即可。

环境要求

• 服务器：安装包只有 Linux x86_64 一种
• 系统服务：从 CentOS 7 自带的 systemd 219 起都兼容
• 数据库：向导建表要求 MySQL 8.0 及以上，MariaDB 和 8.0 以下的 MySQL 会被拒绝
• 缓存：向导只检查 Redis 能否连通，不检查版本，请装 6.2 及以上
• 时区：库里的时间不带时区，按服务器时区记录，服务器请保持 UTC+8
• 本机端口：2282 是网关，nginx 把请求转给它；只听 127.0.0.1，不用对外开放；2282 被别的程序占用时网关起不来

MySQL、Redis、nginx 在宝塔里安装即可。服务器还要能访问外网，收款请求要发到各支付通道。

上传安装包

拿到发行包（zpay-版本号.tar.gz）之后，按下面三步把这个安装包上传到服务器并解压；包没有解压密码。

1. 把域名解析到服务器，在宝塔「网站」里为这个域名建好站点。站点目录默认在 /www/wwwroot/ 下，以域名命名。
2. 用宝塔「文件」把安装包上传到站点目录。
3. 打开宝塔「终端」，进入站点目录解压：

cd /www/wwwroot/你的站点目录
tar -xzf zpay-版本号.tar.gz -C /www/wwwroot/你的站点目录 --strip-components=1

把命令里的 你的站点目录 换成实际的目录名，版本号 换成安装包文件名里的版本号。安装包最外层是一个 zpay-版本号 目录，--strip-components=1 会去掉这一层；解压后站点目录下直接是 runtime、admin、user、templates、static、install 六个目录，以及 version.json、changelog.json。

装成系统服务

在宝塔「终端」里依次执行：

cd /www/wwwroot/你的站点目录
chmod -R u=rwX,go=rX .
chmod 755 runtime/bin/*
cd runtime/bin
sudo ./zpay-supervisor install

两条 chmod 把文件权限改对，install 接着做这几件事：

• 装好系统服务 rzpay.target、rzpay-gateway.service、rzpay-worker.service，并设为开机自启；
• 写出管理命令 /usr/local/bin/zpay，再放一个指向它的 /usr/sbin/zpay；
• 先启动网关的安装向导，worker 等向导写好配置后再启动；
• 把站点目录的 index.html 换成「还差最后一步」页，页上是这台机器要粘贴的 nginx 配置。

终端最后会提示下一步：配置 nginx，再用浏览器打开站点。装好后的权限如下：

• 不要用 chmod -R 777。
• 服务默认以 root 身份运行，文件属主不用改；后台在线更新后要自动重启，也需要 root 身份。
• 站点目录的路径里不能有空格、引号、%、反斜杠，否则 install 会拒绝安装。
• 已经用 root 登录时，命令前的 sudo 可以不写。

配置 nginx

服务装好后打开你的域名，会看到「站长支付已装好服务，还差最后一步：配置 nginx 反向代理」页，页上是这台机器要粘贴的完整配置，端口和站点目录已按本机填好。宝塔给站点生成的配置文件原样保留，只往里加两段。

先清空伪静态

1. 打开「网站 → 设置 → 伪静态」，把编辑框里的内容全选删掉，再保存。在下拉框里选「无」不算清空。
2. 「反向代理」里加过的条目全部删掉。

这两处各带一条 location /，留着会和第二段冲突，nginx 报 duplicate location "/"。

第一段：粘在 server 外

打开「网站 → 设置 → 配置文件」，把下面这段粘在文件最上面、server 那一行之前：

upstream zpay_gateway {
    server 127.0.0.1:2282;
    keepalive 64;
}
map $http_x_forwarded_proto $zpay_forwarded_proto {
    default $scheme;
    https   https;
    http    http;
}

upstream 和 map 只能放在 server { } 外面，放进里面 nginx 起不来。map 让网关知道访客用的是 http 还是 https，前面有 CDN 时也一样。

第二段：粘在 server 里

把下面这段粘进 server { } 里面，建议放在 #REWRITE-END 那一行之后：

client_max_body_size 16m;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $zpay_forwarded_proto;
proxy_set_header Connection "";
proxy_read_timeout 600s;
proxy_send_timeout 600s;
proxy_cache off;
location ^~ /.well-known/ { }
location ^~ / { proxy_pass http://zpay_gateway; }

• location ^~ / 把所有请求交给网关。^~ 不能删：宝塔建站自带的图片、js、css 规则是正则，去掉 ^~ 后会被它们抢先匹配，后台和安装向导的静态文件打不开。
• Host 要用 $http_host，不要改成 $host：用带端口的地址访问时端口会丢，后台打开是一片空白。
• 不要再加 proxy_set_header X-Real-IP $remote_addr，网关从 X-Forwarded-For 里取访客 IP。
• proxy_cache off 关掉反代缓存：查单、回调、收银台都不能被缓存。
• /.well-known/ 那一行让宝塔申请证书时的校验文件照常从磁盘读取；保存时报 duplicate location "/.well-known/" 就删掉这一行。
• server_name、root 和证书设置都不用动。

保存生效

保存配置文件（宝塔保存时会先检查语法），再重载 nginx，然后刷新「还差最后一步」页，就会进入安装向导。

走安装向导

还没安装时，打开站点的任何地址都会跳到安装向导 /install。向导共七步，每一步都实际检测一次，不通过不能往下走：

• 连接数据库：库要先在宝塔里建好，向导不建库；主机默认 127.0.0.1、端口 3306、表前缀 zp_，填好后点「验证并继续」
• 初始化数据库：空库点「下一步」建表；已有站长支付数据的库可以点「下一步」沿用，也可以点「全新安装」删掉这些表重建，删掉的数据无法恢复；缺表的库不能沿用
• 连接 Redis：主机默认 127.0.0.1、端口 6379、10 号库，没设密码就留空
• 站点信息：空库在这一步创建第一个超级管理员，密码 6–16 个字符；库里已有管理员时只核对账号，不创建、不改密码。点「完成安装」写出配置文件 runtime/config/zpay.toml 和安装锁 runtime/.installed
• 安装完成：服务以 root 运行时，5 秒后由 systemd 自动启动网关和 worker，页面每 2 秒检查一次，就绪后点「进入管理后台」；不能自动启动时，页面会提示在终端执行 sudo zpay 并选 1

装好以后再访问 /install 会跳回首页。

注意事项

• install 报 Permission denied：解压时丢了执行权限；后台的 js、css 全是 403 也是这个原因
• 「还差最后一步」页：常见原因是伪静态没清空、反向代理条目没删、粘错了文件、两段位置粘反
• 用 IP 能打开、用域名打不开：要粘的是这个站点自己的配置文件，里面能看到你的 server_name
• 502 与服务没就绪：用 zpay status 看进程，用 journalctl -u rzpay-gateway.service -n 50 看原因
• 重新走安装向导：先备份再删掉 runtime/config/zpay.toml 和 runtime/.installed，执行 sudo zpay 选 3 重启，安装向导会重新出现；库里的数据不受影响

日常启停与排查

管理命令

在服务器终端输入 sudo zpay，输入序号后回车：

站长支付服务管理
  1) 启动
  2) 停止
  3) 重启
  4) 查看状态
  0) 退出
看日志：journalctl -u rzpay-gateway.service -u rzpay-worker.service
请输入序号后回车：

也可以直接带子命令：

sudo zpay start
sudo zpay stop
sudo zpay restart
zpay status

• 菜单和启动、停止、重启都要 root 权限；zpay status 列出每个进程的状态、PID、运行时长和监听端口。
• 提示找不到 zpay 命令时，用全路径 /usr/local/bin/zpay。
• 进程意外退出时，systemd 会在 3 秒后自动重新拉起。
• 安装向导没走完时，启动和重启只会拉起安装向导。

查看日志

sudo journalctl -u rzpay-gateway.service -f
sudo journalctl -u rzpay-worker.service -f

日志文件在站点目录的 storage/logs/gateway/ 和 storage/logs/worker/ 下，每天一个，文件名如 zpay-gateway.log.YYYY-MM-DD。

检查状态

zpay status
curl -fsS http://127.0.0.1:2282/readyz

• /readyz 实际连一次 MySQL 和 Redis，都正常时返回 {"status":"ready"}，否则返回 503。

后台入口

管理后台的地址固定是你的域名加 /admin，商户中心是 /user。站长支付没有另设后台安全入口，不需要找回。

更新程序

登录管理后台，左侧菜单最底部显示当前版本；出现「新版本」或「发现新版本」时点它，在确认框里点「确认更新」。更新终端跑完后，服务按改动范围自动重启，页面自动刷新。

服务不是以 root 身份运行时不能自动重启，终端会提示在服务器执行 sudo zpay restart。