docs: add guided panel deployment

2026-05-01 01:14:10 +05:30 · 2026-04-29 12:50:06 +10:00
parent fa3fdd1a1c
commit 68eac100f2
5 changed files with 609 additions and 24 deletions
--- a/README.md
+++ b/README.md
@@ -94,15 +94,21 @@ J-Board 只保存售卖和展示所需的节点、入站、客户端镜像数据

 ## 环境变量

-以 `.env.example` 为准，运行至少需要：
+以 `.env.example` 为准。生产部署推荐直接使用一键脚本生成 `.env`，手动配置时请重点确认这些值：

- `DATABASE_URL`
- `NEXTAUTH_SECRET`
- `NEXTAUTH_URL`
- `ENCRYPTION_KEY`
- `REDIS_URL`
+| 变量 | 用途 | 说明 |
+| --- | --- | --- |
+| `APP_PORT` | 面板监听端口 | 默认 `3000`。反向代理应转发到 `http://127.0.0.1:APP_PORT`。 |
+| `SITE_NAME` | 站点名称 | 初始化系统设置和邮件模板会使用。 |
+| `NEXTAUTH_URL` | 公网访问地址 | 必须填写你准备反代到面板的正式域名，例如 `https://panel.example.com`。不要填容器内地址。 |
+| `NEXTAUTH_SECRET` | 登录会话密钥 | 生产环境必须使用随机长字符串。 |
+| `ENCRYPTION_KEY` | 敏感信息加密密钥 | 至少 32 字节。生产使用后不要更换，否则 3x-ui 密码、探测 Token、流媒体凭据等已加密数据会无法解密。 |
+| `DATABASE_URL` | PostgreSQL 连接 | 本地工具使用；Docker 部署时 Compose 会覆盖为容器内数据库地址。 |
+| `POSTGRES_PASSWORD` | Docker PostgreSQL 密码 | 一键脚本会自动生成。 |
+| `REDIS_URL` | Redis 连接 | 本地工具使用；Docker 部署时 Compose 会覆盖为容器内 Redis 地址。 |
+| `ADMIN_EMAIL` / `ADMIN_PASSWORD` / `ADMIN_NAME` | 初始管理员 | 首次 `db:seed` 创建管理员账号。已有数据库不会强制重置旧管理员密码。 |

-`ENCRYPTION_KEY` 必须至少 32 字节，用于 3x-ui 面板密码、探测 Token、流媒体凭据等敏感信息加密。Docker 部署时 `DATABASE_URL` 与 `REDIS_URL` 会由 `docker-compose.yml` 覆盖为容器内地址。
+SMTP 邮件服务、注册邮箱验证开关、支付方式、3x-ui 节点等业务配置都在管理后台填写，不建议写进 `.env`。

 ## 本地开发

@@ -135,11 +141,75 @@ npm run build
 - 不维护 Prisma migrations，不提交迁移脚本
 - 删除字段或模型时同步清理引用、文档和导出逻辑

-## Docker 部署
+## 部署
+
+### 一键部署（推荐）
+
+适合全新的 Linux 服务器。脚本会自动安装 Docker 与 Compose 插件，拉取代码，询问并生成 `.env`，初始化数据库，启动面板，最后输出访问地址、反代目标和管理员账号。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/JetSprow/J-Board/main/scripts/install-jboard-panel.sh | bash
+```
+
+脚本会询问这些信息；直接回车即可使用默认值或自动生成值：
+
+| 提示项 | 含义 |
+| --- | --- |
+| 安装目录 | 默认 `/opt/jboard`；如果在仓库内运行脚本则默认当前仓库。 |
+| 站点名称 | 面板标题、邮件模板和初始化系统设置会使用。 |
+| 公网访问地址 | 你准备反向代理到本机 `3000` 端口的域名，例如 `https://panel.example.com`。没有域名时可先用 `http://服务器IP:3000` 测试。 |
+| 本机监听端口 | 默认 `3000`，Nginx/Caddy/宝塔反代目标就是 `http://127.0.0.1:3000`。 |
+| 管理员邮箱和密码 | 首次初始化会创建该管理员，脚本完成后会再次打印。 |
+| PostgreSQL 密码、`NEXTAUTH_SECRET`、`ENCRYPTION_KEY` | 可手动输入；回车会自动生成安全值。 |
+
+也可以用环境变量覆盖默认行为：
+
+```bash
+APP_DIR=/opt/jboard GH_REPO=JetSprow/J-Board BRANCH=main bash <(curl -fsSL https://raw.githubusercontent.com/JetSprow/J-Board/main/scripts/install-jboard-panel.sh)
+```
+
+脚本完成后，你会看到类似信息：
+
+```text
+访问地址：https://panel.example.com
+反代目标：http://127.0.0.1:3000
+管理员邮箱：admin@example.com
+管理员密码：自动生成或你输入的密码
+```
+
+### 反向代理
+
+`NEXTAUTH_URL` 和后台“系统设置 -> 站点域名 / URL”都应该填写公网域名，也就是你准备给用户访问、并反向代理到 J-Board 的域名。不要填写 `localhost`、容器名或内网地址。
+
+Nginx 示例：
+
+```nginx
+server {
+  listen 80;
+  server_name panel.example.com;
+
+  location / {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    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_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+  }
+}
+```
+
+正式上线建议再用 Certbot、宝塔、1Panel、Caddy 或 CDN 申请 HTTPS 证书，然后把 `NEXTAUTH_URL` 改为 `https://panel.example.com`。
+
+### 手动 Docker 部署

 首次启动：

 ```bash
+cp .env.example .env
+# 编辑 .env，尤其是 NEXTAUTH_URL、NEXTAUTH_SECRET、ENCRYPTION_KEY、POSTGRES_PASSWORD、管理员账号
 docker compose build init app
 docker compose --profile setup run --rm init
 docker compose up -d app
@@ -154,12 +224,54 @@ docker compose --profile setup run --rm init sh -lc 'npm run db:push'
 docker compose up -d app
 ```

+仓库内也提供更新脚本：
+
+```bash
+./scripts/upgrade-jboard-panel.sh
+```
+
 常用排障：

 - 查看状态：`docker compose ps`
 - 查看日志：`docker compose logs -f app`
 - 页面仍是旧版本：确认已执行 `docker compose build init app` 和 `docker compose up -d app`
 - Schema 没有生效：单独运行 `docker compose --profile setup run --rm init sh -lc 'npm run db:push'`
+- 登录回调、邮件链接或支付回跳出现 `localhost`：检查 `.env` 里的 `NEXTAUTH_URL` 和后台系统设置里的站点域名。
+
+### 部署后检查清单
+
+1. 登录 `/admin`，进入“系统设置”，确认站点域名就是你的反代域名。
+2. 配置 SMTP 邮件服务并点击“测试”，再按需要开启注册邮箱验证。
+3. 进入“支付配置”，填写并启用至少一种支付方式。
+4. 添加 3x-ui 节点，测试连接并同步入站。
+5. 创建套餐，绑定入站或流媒体服务。
+6. 用普通用户注册、下单、支付、查看订阅，走一遍完整流程。
+
+可以展示给用户的常用入口：
+
+- 登录：`https://你的域名/login`
+- 注册：`https://你的域名/register`
+- 套餐商店：`https://你的域名/store`
+- 用户中心：`https://你的域名/dashboard`
+- 订阅列表：`https://你的域名/subscriptions`
+
+## 支付配置
+
+支付配置在后台 `/admin/payments` 完成，密钥会保存在数据库中，不写入 `.env`，也不要提交到仓库或截图外传。创建订单时，系统会根据用户选择的支付方式生成支付链接、二维码或链上收款信息；支付成功后进入 `src/services/payment/process.ts` 完成订单确认和订阅开通。
+
+| 支付方式 | 适用场景 | 必填信息 | 回调 / 查询说明 |
+| --- | --- | --- | --- |
+| 易支付 | 第三方聚合支付，常用于支付宝/微信通道 | API 地址、商户 ID、商户密钥、启用渠道 | 通知地址为 `https://你的域名/api/payment/notify/epay`。支持 `alipay`、`wxpay` 渠道。 |
+| 支付宝当面付 | 支付宝官方扫码支付 | App ID、应用私钥、支付宝公钥、网关地址 | 通知地址为 `https://你的域名/api/payment/notify/alipay_f2f`，也支持订单查询兜底。 |
+| USDT TRC20 | 加密货币收款 | TRC20 钱包地址、汇率，可选 TronGrid API Key | 没有传统回调，系统按订单金额查询近期 TRC20 入账。建议配置 TronGrid API Key 提高稳定性。 |
+
+支付上线前建议：
+
+- 在支付平台后台把通知域名、回跳域名、应用网关白名单都设置为你的公网域名。
+- 先创建低金额测试套餐，确认“创建订单 -> 支付 -> 回调/查询 -> 自动开通订阅”完整可用。
+- 易支付的 API 地址不要带尾部路径，例如填 `https://pay.example.com`，系统会自动请求 `/mapi.php`、`/submit.php` 和 `/api.php`。
+- 支付宝密钥可以填写纯 key 内容或 PEM 格式；系统会自动补 PEM 包装。
+- USDT TRC20 按金额匹配入账，测试时避免短时间出现多笔完全相同金额。

 ## 节点与探测

@@ -197,6 +309,7 @@ docker compose exec -T db pg_dump -U jboard jboard > backup_$(date +%Y%m%d_%H%M%
 安全建议：

 - 不要提交 `.env`、探测 Token、3x-ui 密码、支付密钥
+- 数据库备份里包含用户、订单和支付配置，建议加密保存并限制下载权限
 - 生产环境不要公开 PostgreSQL 和 Redis 端口
 - 3x-ui 面板建议限制来源 IP 或使用反向代理鉴权
 - `ENCRYPTION_KEY` 一旦生产使用不要随意更换，否则已加密数据会无法解密