一键部署

一句话

准备好一台服务器和一个已解析的域名，把文件夹放到电脑上，跑一行命令，等 5~10 分钟。

你需要先有的三样东西

	说明
一台服务器	8 核 8G 起，公网 IP，推荐 coresserver
一个域名	推荐 cloudflare 或者 godaddy
电脑上装了 Python	见装 Python

服务器配置别省

2G 内存跑不动（后端 JVM + Next.js + MySQL + Redis 挤在一起会 OOM）。 4G 是下限，8G 更稳。

系统必须是 Ubuntu 22.04

脚本按 Ubuntu 的包管理器写的。CentOS / Debian / Alpine 都不行。买服务器时选「Ubuntu 22.04 LTS」。推荐服务器 coresserver

第 1 步：把域名解析到服务器

去你买域名的地方（Cloudflare / GoDaddy…），加两条 A 记录：

类型	主机记录	记录值
A	`@`	你的服务器 IP
A	`www`	你的服务器 IP

这一步必须在部署之前做完

HTTPS 证书是靠"访问你的域名"来验证所有权的。域名还没指过来的话签不下来，部署会卡在最后一步。

改完等几分钟生效（有的服务商要十几分钟）。

怎么确认生效了：在终端敲

bash

ping 你的域名

回显的 IP 是你的服务器 IP 就好了。

第 2 步：把文件放到电脑上

你需要这 5 个文件：

mall.jar        后端
client.zip      商城前台
admin.zip       管理后台
deploy.py       部署脚本
build.json      版本信息

两个来源，任选一个：

来源	怎么拿
我们给你的文件夹	解压出来就是这 5 个，直接用
GitHub Releases	github.com/qijipower-web/qiji-mall/releases —— 在 Assets 里逐个下载，永远是最新版

5 个文件要在同一个文件夹里

脚本靠"我旁边有没有 mall.jar"来判断自己是不是在分发包里。把 deploy.py 单独拎出去跑是不行的。

第 3 步：跑一次，它会生成配置文件

在那个文件夹里打开终端，敲：

bash

python deploy.py

怎么在某个文件夹打开终端

Windows：在文件夹的地址栏里输 cmd 按回车。 macOS：右键文件夹 → 服务 → 新建位于文件夹位置的终端窗口。

第一次跑，它不会真的部署，而是在同目录生成一个 .secrets.json，然后停下来：

[OK] 已生成 .secrets.json（各种密钥都随机生成好了）

==================================================================
  还差几项配置，需要你手动填一下
==================================================================
  文件：...\.secrets.json

    "host"            <- 服务器 IP
    "ssh_user"        <- SSH 用户名
    "ssh_password"    <- SSH 密码
    "domain"          <- 域名

  填完保存，再跑一次：  python deploy.py

第 4 步：填 `.secrets.json`

用记事本（或任何文本编辑器）打开它。完整长这样 —— 这就是全部内容，没有别的文件：

json

{
  "host": "<server IP, e.g. 1.2.3.4>",
  "ssh_user": "<usually root>",
  "ssh_port": 22,
  "ssh_password": "<your server SSH password>",
  "domain": "<your domain, no https://, e.g. a.com>",
  "cert_email": "",
  "admin_init_username": "admin",
  "mysql_password": "VJIA9JDhKGjTdHTVZw58fvS-",
  "app_encrypt_key": "O1Mr3LFfHEalbBBrbPbZvt3Cz1nfvkwtW9Bqq/TWSE8=",
  "satoken_secret": "5e62cb6adfaab1697f2e3b516b51503455efbe8d21319c461fd9af5a4d7efd2a",
  "admin_init_password": "Mall@a0fe4f8f",
  "redis_password": ""
}

一眼分辨该填哪些：看有没有尖括号

<...> 里的内容是占位提示，把整个（含尖括号）替换成你自己的值。没有尖括号的那几行是自动生成的密钥，不用动。

🖊️ 你要填的（4 项）

字段	填什么	改成
`host`	服务器的公网 IP。服务商开通后会给你	`"1.2.3.4"`
`ssh_user`	登录服务器的用户名。绝大多数是 `root`，有的服务商给 `ubuntu`	`"root"`
`ssh_password`	那个用户的密码。服务商给的，或你自己设的	`"aB3#kL9@mN2"`
`domain`	你的域名，不带 `https://`、不带斜杠、不带 `www.`	`"a.com"`

改完这四行长这样：

json

  "host": "1.2.3.4",
  "ssh_user": "root",
  "ssh_port": 22,
  "ssh_password": "aB3#kL9@mN2",
  "domain": "a.com",

host 要填公网 IP，不是内网 IP

服务商的控制台上通常会同时显示两个。内网 IP 一般是 10.x.x.x、172.16~31.x.x、 192.168.x.x 开头的 —— 那个从你家里连不上。

密码直接粘贴就行

不用担心密码多长多乱、带多少符号。这里是文本编辑器，你看得见自己粘的是什么，也能反复改 —— 这正是不做成"终端里盲输密码"的原因。

⚙️ 可以改但通常不用改（2 项）

字段	说明
`ssh_port`	SSH 端口。默认 `22`，只有服务商改过或你自己改过才需要动。注意它是数字，不加引号
`cert_email`	HTTPS 证书相关通知的邮箱。留空完全没问题（见本页末尾「Let's Encrypt 已不再发到期提醒邮件」）
`admin_init_username`	后台登录用的用户名，默认 `admin`。强烈建议改掉，见下

⭐ 强烈建议改掉 `admin_init_username`

默认是 admin。改成别的，比如：

json

  "admin_init_username": "jdz-boss",

为什么值得改

admin 是全世界爆破字典里的第一个词。用它的话攻击者只需要猜密码；换一个别人猜不到的名字，等于账号和密码两样都得猜。

系统对登录做了两把限流锁（按账号 + 按 IP），但那是在有人开始猜之后才起作用 —— 换个用户名是让他连从哪儿下手都不知道。

规则：3~32 位，只能用字母、数字、下划线 _、连字符 -。不能有空格、中文、@。填错了部署时就会告诉你，不会等到登录才发现。

它只在第一次部署时生效

账号一旦建进数据库，改这个字段就不再有任何作用 —— 不会重命名已有账号。

已经部署过了想改名：去后台新建一个管理员并给超管角色，用新账号登录后把旧的停用。见管理员与权限。

🔒 自动生成的密钥（不要动）

这几项脚本已经随机生成好了，改了会出问题：

字段	是什么	改了会怎样
`app_encrypt_key`	最重要的一个。AES-256 主密钥，用来加密数据库里的 Stripe/PayPal 密钥、发信 API Key、二次验证种子	换掉 = 已保存的支付配置全部作废，要重新填一遍
`mysql_password`	数据库密码	和服务器上的对不上，后端连不上库
`satoken_secret`	登录令牌的签名密钥。同时用来给前端缓存刷新接口签名	所有人被踢下线，缓存刷新失效
`admin_init_password`	后台超级管理员的初始密码。部署完终端会打印它	部署前改还有效，部署后改就没意义了（库里已经建好账号）
`redis_password`	缓存密码。首次部署时才生成，所以现在是空的	同 mysql_password

app_encrypt_key 丢了没有第二把钥匙

数据库里存的是密文，能解开它的只有这一个值，而且它只存在你这台电脑上 （服务器上有一份副本，但服务器没了就一起没了）。

丢了的表现：后端能启动，但支付通道全部报「配置解析失败」，你得把 Stripe / PayPal 的密钥重新填一遍。订单和钱不受影响，但很麻烦。

填完这个文件之后，立刻复制一份到 U 盘或网盘。

📝 关于 `admin_init_password`

它就是你第一次登录后台要用的密码，配套的用户名是上面那个 admin_init_username。

想用自己好记的密码？现在就改

部署之前改这一项是有效的，比如改成 "MyShop2026!"。部署之后再改就没用了 —— 那时账号已经建进数据库，改密码要去后台改。

⚠️ 保存时的三个坑

一、别删逗号、别用中文引号

JSON 对标点很挑剔。最常见的两种写坏方式：

json

"host": "1.2.3.4"      ← 后面少了逗号
"host"： "1.2.3.4",    ← 冒号是中文的 ：

存坏了脚本会告诉你第几行有问题，改回来就行。

二、编码要 UTF-8

记事本现在默认就是 UTF-8，正常不用管。如果脚本报「不是 UTF-8 编码」，用记事本打开 →「另存为」→ 右下角编码选 UTF-8 再保存。

三、别把文件改名或挪走

脚本只认和 deploy.py 同一个文件夹里的 .secrets.json。

文件名以点开头，在文件管理器里可能看不见

Windows：资源管理器 → 查看 → 勾上「隐藏的项目」。 macOS：在 Finder 里按 Cmd + Shift + .

也可以在终端里直接用记事本打开：

bash

notepad .secrets.json

第 5 步：再跑一次

bash

python deploy.py

这次就真的开始部署了。它会依次做这些事，每一步都有进度：

检查域名解析      ← 没解析会在这里停下并告诉你怎么办
装环境            JDK / MySQL / Redis / Nginx（第一次约 3~5 分钟）
上传产物          三个包
写配置            .env / systemd / nginx
申请 HTTPS 证书   自动，不用管
启动服务
写入站点域名      ← 所以你不用去后台填域名
健康检查

5~10 分钟后会打印：

==================================================================
  部署完成
==================================================================
  商城首页   https://a.com/
  管理后台   https://a.com/admin/
  ...
  初始管理员 jdz-boss / Mall@xxxxxxxx   <- 登录后立即修改

以后想改配置，直接改这个文件

换服务器？改 host 和 ssh_password。换域名？改 domain。改完重跑 python deploy.py 即可，脚本永远以这个文件为准。

第 6 步：⭐ 立刻做的两件事

① 备份 `.secrets.json`

这个文件丢了，已保存的支付密钥全部作废

里面的 app_encrypt_key 是加密 Stripe/PayPal 密钥的主密钥。它不在服务器上，只在你电脑上这一份。

现在就复制一份到 U 盘或网盘。

② 登录后台改密码

打开 https://你的域名/admin/，用上面打印的账号和密码登录（账号就是你在 admin_init_username 里填的那个），右上角改密码。

之后要做什么

按上线清单走一遍。最要紧的两项：

发信服务 —— 不配的话买家收不到验证码，注册不了
支付通道 —— 不配的话收不到钱

更新到新版本

拿到新的一批文件（我们发给你，或者去 GitHub Releases 下），覆盖掉旧的（.secrets.json 不要覆盖），然后：

bash

python deploy.py update

比第一次快很多（不用再装环境、不用再签证书）。

只更新其中一个

bash

python deploy.py update backend

front / admin 同理。

后端是开源的

github.com/qijipower-web/qiji-mall —— AGPL-3.0 许可证。

仓库里是后端的全部源码和 deploy.py。这意味着两件事：

你可以先读一遍 `deploy.py` 再跑它

它是唯一接触你 SSH 密码的东西，所以我们把它做成纯文本的 Python，不是编译产物 —— 打开就能从头读到尾，看清楚它到底往你服务器上做了什么。

它不做这些事：不回连任何服务器、不上报、不检查更新。你可以自己确认 —— 文件里没有一处对外的 HTTP 请求（除了在你的服务器上 apt 装东西和下载 Node）。

你可以自己编译 `mall.jar`

不想用我们发的那个，就自己编一个：

bash

git clone https://github.com/qijipower-web/qiji-mall.git
cd qiji-mall/Backend
mvn clean package -DskipTests

产物在 Backend/target/mall.jar。把它覆盖掉你那 5 个文件里的 mall.jar，然后照常：

bash

python deploy.py update backend

脚本只认 mall.jar 这个文件名，不在乎它是谁编的。

需要本机有 JDK 21 和 Maven 3.9+。

自己编出来的 jar 和我们发的不会一模一样

这是正常的，不是被人动过手脚。Java 的 jar 里带着编译时间戳和文件顺序，两次编译出来的字节几乎必然不同 —— 哪怕源码一个字符都没改。所以拿 SHA-256 去比对是没有意义的。

有意义的验证是：编一个自己的，然后用自己的那个。 上面那三行命令就是全部。

商城前台和管理后台不开源

client.zip 和 admin.zip 是构建好的前端资源，源码暂不公开。如果你需要改前台样式或后台交互，这个仓库满足不了你。

但如果你关心的是服务器上跑的是什么、数据往哪走、有没有回连 —— 那些全部发生在后端和 deploy.py，而这两样都在仓库里，可读、可编译、可替换。

常见问题

停在「检查域名解析」

它已经告诉你要做什么了 —— 去域名商那里加 A 记录，等几分钟再重跑。

如果你在用 Cloudflare 的小黄云（代理模式），解析出来的是 Cloudflare 的 IP，脚本会警告但继续跑。证书签不下来的话，先把小黄云点成灰云，签完再打开。

连不上服务器

脚本会按错误类型告诉你查什么。三种最常见的：

报错	通常是
密码或用户名不对	`ssh_password` 复制时带了空格；或 `ssh_user` 不是 root（有的服务商给 `ubuntu`）；或服务器禁用了密码登录
连不上这个地址和端口	`host` 填成了内网 IP；或安全组没放行 22 端口
握手就失败了	IP 打错了；或服务器还在开机中

改 .secrets.json 里对应的那一项，重跑即可。

报 不是合法的 JSON

编辑时把逗号或引号弄坏了。脚本会告诉你第几行。

最常见的两种：少了/多了逗号、用了中文引号 “”。

报 不是 UTF-8 编码

编辑器把文件存成 ANSI/GBK 了。用记事本打开 →「另存为」→ 编码选 UTF-8。

报 请先安装依赖: pip install paramiko

见装 Python 最后那一步。

证书没签下来，站点跑在 http 上

脚本会明确告诉你，并列出三个常见原因。修好之后重跑一次 python deploy.py 就会补签 —— 已经装好的部分不会重来。

部署成功了，但打开域名是 502

后端还在启动（第一次要跑数据库迁移，可能要 1~2 分钟）。等一会儿刷新。还是不行就：

bash

python deploy.py logs backend

想换一台服务器

改 .secrets.json 里的 host 和 ssh_password，重跑 python deploy.py。 但数据不会跟着走 —— 先在旧机上 python deploy.py backup 导出，新机部署完再恢复。见备份。

想换域名

改 .secrets.json 里的 domain，重跑 python deploy.py。它会重签证书、改 nginx、更新数据库里的域名。

⚠️ 老域名的链接会失效，搜索引擎收录也要重新来。

想确认脚本本身没问题

bash

python deploy.py selftest

不连服务器，几秒出结果。

HTTPS 证书会自己续期，不用管

装完就是自动的

证书是 Let's Encrypt 签的，有效期 90 天 —— 但续期是全自动的：部署时装的 certbot 自带一个定时器，每天检查两次，到期前 30 天自动续，续完自己重载 nginx。

你不需要记任何日期，也不需要做任何事。

想确认它在正常工作：

bash

python deploy.py check

会告诉你证书在不在、自动续期的定时器活着没。

Let's Encrypt 不再发到期提醒邮件了

2025 年 6 月起停发。所以 cert_email 填了也不会收到提醒 —— 它现在只在证书出问题时可能用得上，留空完全没关系。

真正的保障是那个定时器，不是邮件。

什么情况下续期会断

都是你自己动了配置的时候：改了 nginx 却没走 deploy.py、域名改了解析、80 端口被防火墙挡住。

只用 python deploy.py 管理服务器，就不会碰到这些。

服务器重启 / 断电后，会自己起来

什么都不用做

部署时所有服务都设成了开机自启，断电、重启、服务商维护之后，机器一开机它们就自己回来了。

启动顺序也是排好的：

MySQL + Redis  →  后端  →  前端

而且每个服务都是「挂了自动重启」。所以就算断电后 MySQL 恢复数据花的时间长一点、后端先起来连不上库，它也会每 5 秒重试一次，直到连上为止 —— 自己会好。

唯一要注意：起来需要一两分钟

后端要等 MySQL 就绪，前端要等后端就绪。重启后别刚开机就急着刷新，等 1~2 分钟。

想确认这一项没问题：

bash

python deploy.py check

它会逐个检查 7 个服务的开机自启（后端 / 前端 / 对象存储 / Nginx / MySQL / Redis / 定时任务），以及有没有服务处于失败状态。

「现在跑得好好的」不等于「下次开机还会跑」

这两件事是分开的。手工启动的服务照样显示在运行，但没设开机自启的话， 断一次电站点就再也不回来了，而且没有任何征兆 —— 你要等到有人告诉你打不开。

所以这一项才值得用命令查，而不是"看着能访问就行"。

一键部署 ​

你需要先有的三样东西 ​

第 1 步：把域名解析到服务器 ​

第 2 步：把文件放到电脑上 ​

第 3 步：跑一次，它会生成配置文件 ​

第 4 步：填 .secrets.json ​

🖊️ 你要填的（4 项） ​

⚙️ 可以改但通常不用改（2 项） ​

⭐ 强烈建议改掉 admin_init_username ​

🔒 自动生成的密钥（不要动） ​

📝 关于 admin_init_password ​

⚠️ 保存时的三个坑 ​

第 5 步：再跑一次 ​

第 6 步：⭐ 立刻做的两件事 ​

① 备份 .secrets.json ​

② 登录后台改密码 ​

之后要做什么 ​

更新到新版本 ​

后端是开源的 ​

你可以先读一遍 deploy.py 再跑它 ​

你可以自己编译 mall.jar ​

常见问题 ​

HTTPS 证书会自己续期，不用管 ​

服务器重启 / 断电后，会自己起来 ​

一键部署

你需要先有的三样东西

第 1 步：把域名解析到服务器

第 2 步：把文件放到电脑上

第 3 步：跑一次，它会生成配置文件

第 4 步：填 `.secrets.json`

🖊️ 你要填的（4 项）

⚙️ 可以改但通常不用改（2 项）

⭐ 强烈建议改掉 `admin_init_username`

🔒 自动生成的密钥（不要动）

📝 关于 `admin_init_password`

⚠️ 保存时的三个坑

第 5 步：再跑一次

第 6 步：⭐ 立刻做的两件事

① 备份 `.secrets.json`

② 登录后台改密码

之后要做什么

更新到新版本

后端是开源的

你可以先读一遍 `deploy.py` 再跑它

你可以自己编译 `mall.jar`

常见问题

HTTPS 证书会自己续期，不用管

服务器重启 / 断电后，会自己起来