[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2956":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":15,"lastSyncTime":27,"discoverSource":28},2956,"J-Board","JetSprow\u002FJ-Board","JetSprow","JetSprow's Board for 3X-UI",null,"TypeScript",109,20,95,0,2,11,6,3.97,"MIT License",false,"main",true,[],"2026-06-12 02:00:45","# J-Board\n\nJ-Board（也称 JB 面板）是一个面向代理订阅售卖与流媒体共享的全栈管理面板。它负责用户、套餐、订单、支付、订阅、工单、邮件、公告、审计、探测展示与订阅风控；节点实际运行、入站协议、Xray 客户端配置仍由 3x-ui 维护。\n\nJ-Board 的定位很明确：它不是新的节点控制面，也不替代 3x-ui。它把售卖、开通、订阅交付、售后和风险审查做成一个完整面板，并通过只读 Agent 从节点侧采集延迟、路由和 Xray access log 证据。\n\n\n## 快速认识\n\n```text\n用户浏览器 \u002F 客户端订阅\n  ↓\nNext.js App Router 面板\n  ├─ PostgreSQL：用户、订单、套餐、订阅、审计、风控事件\n  ├─ Redis：限流、后台任务与缓存辅助\n  ├─ 3x-ui API：同步入站、开通\u002F暂停\u002F删除代理客户端\n  └─ Agent API：接收 jboard-agent 上报的延迟、路由、节点真实连接日志\n\n节点 VPS\n  ├─ 3x-ui \u002F Xray：真实入站、客户端、流量限制与代理运行\n  └─ jboard-agent：旁路只读探测与日志聚合，不修改 3x-ui 配置\n```\n\nJ-Board 只保存售卖和展示需要的节点镜像数据。入站协议、端口、Reality\u002FTLS、Xray 运行状态和客户端真实配置仍以 3x-ui 为准。\n\n## 功能概览\n\n用户端：\n\n- 注册、登录、邮箱验证、忘记密码、邮箱变更验证。\n- 支持 Cloudflare Turnstile 人机验证。\n- 代理套餐和流媒体套餐购买、续费、增流量。\n- 购物车、订单、支付状态查询和支付方式切换。\n- 代理订阅查看、订阅链接下载、订阅访问重置。\n- 线路体验展示：三网延迟、延迟历史、三网路由追踪。\n- 流媒体订阅凭据展示。\n- 通知中心、工单售后、账号资料、邀请码。\n- 暗色\u002F夜间模式和移动端适配。\n\n管理端：\n\n- 3x-ui 节点管理：保存面板地址、账号、密码，测试连接并同步入站。\n- 本地入站展示名维护，套餐绑定同步后的入站线路。\n- 探测 Token 管理：用于 Agent 上报延迟、路由和节点日志。\n- 用户、订单、套餐、订阅、流媒体服务、支付配置。\n- SMTP 邮件服务设置、注册邮箱验证开关、邮件模板发送。\n- 公告、工单、系统设置、审计日志、任务中心、备份恢复。\n- 支持工单上限配置，默认每个用户最多开启 2 个未关闭工单。\n- 流量视图：基于本地订阅与 3x-ui 同步结果展示客户端用量。\n- 订阅访问风控：IP、城市、省\u002F地区、国家变化审查。\n- 节点日志风控：基于 Xray access log 分析真实来源 IP、连接数、不同目标数。\n- 风控人工处理：查看用户、订阅、地图、IP、分析日志，生成风险报告，选择解除限制或保持封禁\u002F暂停。\n\n节点侧：\n\n- 3x-ui 负责入站、客户端、协议配置和节点运行。\n- J-Board 通过 3x-ui API 同步入站并执行客户端增删改。\n- `agent\u002Fjboard-agent` 负责三网 TCP 延迟、三网路由追踪和可选 Xray access log 风控上报。\n- Agent 只读日志文件，不重启 Xray，不修改 3x-ui 配置。\n\n## 版本与发布规则\n\nJ-Board 面板和 Agent 使用相对独立的版本节奏。\n\n- 面板代码变更可以只提交到 `main`，不一定创建 GitHub Release。\n- Agent 二进制发生变化时，才需要升级 Agent 版本、打 tag、创建 Release，并上传 `jboard-agent-linux-amd64`、`jboard-agent-linux-arm64`、`SHA256SUMS`。\n- Agent 安装\u002F升级脚本默认下载 GitHub 最新 Release 中的 Agent 产物。\n- 不要为了普通网站页面或后台文案改动强行更新 Agent tag。\n\n当前项目版本写在 `package.json`，Agent 运行时版本写在 `agent\u002Fjboard-agent\u002Fcmd\u002Fagent\u002Fmain.go`，Agent 构建版本写在 `agent\u002Fjboard-agent\u002FMakefile`。\n\n## 技术栈\n\n- Next.js 16 App Router + React 19\n- Prisma 7 + PostgreSQL 16\n- NextAuth 4 Credentials\n- Redis 7\n- Tailwind CSS 4 + Base UI + Sonner + Recharts\n- Nodemailer SMTP 邮件\n- MaxMind MMDB GeoIP\n- Go jboard-agent\n- Docker \u002F Docker Compose\n\n注意：本项目使用的 Next.js 版本包含和旧版本不同的约定。开发前请阅读 `AGENTS.md`，并按 `node_modules\u002Fnext\u002Fdist\u002Fdocs\u002F` 中的当前文档实现。\n\n## 目录结构\n\n| 路径 | 说明 |\n| --- | --- |\n| `src\u002Fapp` | 页面、布局、Route Handlers。 |\n| `src\u002Factions` | Server Actions，负责写操作、权限校验、审计和缓存刷新。 |\n| `src\u002Fservices` | 领域服务与第三方适配。 |\n| `src\u002Fservices\u002Fnode-panel` | 3x-ui 面板适配层。 |\n| `src\u002Fservices\u002Fprovision.ts` | 支付成功后的订阅开通与 3x-ui 客户端同步。 |\n| `src\u002Fservices\u002Fsubscription-risk.ts` | 订阅访问与节点日志风控判定。 |\n| `src\u002Fservices\u002Fsubscription-risk-review.ts` | 风控事件证据整理、报告生成辅助。 |\n| `src\u002Flib` | Prisma、鉴权、加密、Turnstile、GeoIP、工具函数。 |\n| `prisma\u002Fschema.prisma` | 数据模型事实源。 |\n| `data\u002FGeoLite2-City.mmdb` | 默认 GeoIP 城市库。 |\n| `agent\u002Fjboard-agent` | Go Agent 源码、构建脚本和 Agent 文档。 |\n| `scripts\u002Finstall-jboard-panel.sh` | 面板一键安装向导。 |\n| `scripts\u002Fupgrade-jboard-panel.sh` | 面板升级脚本。 |\n| `scripts\u002Finstall-jboard-agent.sh` | Agent 安装脚本。 |\n| `scripts\u002Fupgrade-jboard-agent.sh` | Agent 升级脚本。 |\n| `docs\u002FAPI.md` | HTTP 接口与 Server Actions 参考。 |\n| `docs\u002Fopenapi.yaml` | 对外 HTTP 接口 OpenAPI 描述。 |\n\n## 环境变量\n\n以 `.env.example` 为准。生产部署推荐使用一键脚本生成 `.env`，手动配置时重点确认下列变量。\n\n| 变量 | 用途 | 说明 |\n| --- | --- | --- |\n| `APP_PORT` | 面板监听端口 | 默认 `3000`。反向代理应转发到 `http:\u002F\u002F127.0.0.1:APP_PORT`。 |\n| `SITE_NAME` | 站点名称 | 初始化系统设置和邮件模板会使用。 |\n| `NEXTAUTH_URL` | 网站访问地址 | 必须填写准备反代到面板的正式域名，例如 `https:\u002F\u002Fpanel.example.com`。不要填 `localhost`、容器名或内网地址。 |\n| `SUBSCRIPTION_URL` | 订阅访问地址 | 可选。用于生成客户端订阅链接，例如 `https:\u002F\u002Fsub.example.com`；留空时复用 `NEXTAUTH_URL`。 |\n| `NEXTAUTH_SECRET` | 登录会话密钥 | 生产环境必须使用随机长字符串。 |\n| `ENCRYPTION_KEY` | 敏感信息加密密钥 | 至少 32 字节。生产使用后不要更换，否则 3x-ui 密码、探测 Token、SMTP 密码、流媒体凭据等已加密数据会无法解密。 |\n| `DATABASE_URL` | PostgreSQL 连接 | 本地工具使用；Docker 部署时 Compose 会覆盖为容器内数据库地址。 |\n| `POSTGRES_PASSWORD` | Docker PostgreSQL 密码 | 一键脚本会自动生成。 |\n| `REDIS_URL` | Redis 连接 | 本地工具使用；Docker 部署时 Compose 会覆盖为容器内 Redis 地址。 |\n| `GEOIP_MMDB_PATH` | GeoIP 城市库 | 默认 `data\u002FGeoLite2-City.mmdb`。可换成自己的 MaxMind City MMDB。 |\n| `ADMIN_EMAIL` \u002F `ADMIN_PASSWORD` \u002F `ADMIN_NAME` | 初始管理员 | 首次 `db:seed` 创建管理员账号。已有数据库不会强制重置旧管理员密码。 |\n\nSMTP 邮件服务、注册邮箱验证开关、支付方式、3x-ui 节点等业务配置在管理后台填写，不建议写进 `.env`。\n\n## 一键部署\n\n适合全新 Linux 服务器。脚本会安装基础依赖、安装 Docker 与 Compose 插件、拉取代码、生成 `.env`、初始化数据库并启动面板。\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FJetSprow\u002FJ-Board\u002Fmain\u002Fscripts\u002Finstall-jboard-panel.sh)\n```\n\n脚本会交互询问：\n\n| 问题 | 如何填写 |\n| --- | --- |\n| 安装目录 | 默认 `\u002Fopt\u002Fjboard`；如果在仓库内运行脚本则默认当前仓库。 |\n| 站点名称 | 面板标题、邮件模板和初始化系统设置会使用。 |\n| 网站访问地址 | 你准备反向代理到本机 `3000` 端口的面板域名，例如 `https:\u002F\u002Fpanel.example.com`。没有域名时可先用 `http:\u002F\u002F服务器IP:3000` 测试。 |\n| 订阅访问地址 | 用于生成 Clash\u002FV2rayN\u002FShadowrocket 等客户端订阅链接。可以和网站地址相同，也可以填独立订阅域名，例如 `https:\u002F\u002Fsub.example.com`。 |\n| 本机监听端口 | 默认 `3000`。Nginx、Caddy、宝塔或 1Panel 的反代目标就是 `http:\u002F\u002F127.0.0.1:3000`。 |\n| 管理员邮箱和密码 | 首次初始化会创建该管理员，脚本完成后会再次打印。 |\n| PostgreSQL 密码、`NEXTAUTH_SECRET`、`ENCRYPTION_KEY` | 可手动输入；回车会自动生成安全值。 |\n\n也可以通过环境变量覆盖默认行为：\n\n```bash\nAPP_DIR=\u002Fopt\u002Fjboard GH_REPO=JetSprow\u002FJ-Board BRANCH=main bash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FJetSprow\u002FJ-Board\u002Fmain\u002Fscripts\u002Finstall-jboard-panel.sh)\n```\n\n脚本完成后会输出：\n\n```text\n访问地址：https:\u002F\u002Fpanel.example.com\n订阅地址：https:\u002F\u002Fsub.example.com\n反代目标：http:\u002F\u002F127.0.0.1:3000\n管理员邮箱：admin@example.com\n管理员密码：自动生成或你输入的密码\n```\n\n请把管理员密码保存到密码管理器。已有数据库重复部署时，脚本会尽量沿用现有配置，不会随意重置管理员。\n\n## 手动 Docker 部署\n\n首次启动：\n\n```bash\ncp .env.example .env\n# 编辑 .env，尤其是 NEXTAUTH_URL、SUBSCRIPTION_URL、NEXTAUTH_SECRET、ENCRYPTION_KEY、POSTGRES_PASSWORD、管理员账号\ndocker compose build init app\ndocker compose --profile setup run --rm init\ndocker compose up -d app\n```\n\n更新部署：\n\n```bash\ngit pull --ff-only\ndocker compose build init app\ndocker compose --profile setup run --rm init sh -lc 'npm run db:push'\ndocker compose up -d app\n```\n\n仓库内也提供更新脚本：\n\n```bash\n.\u002Fscripts\u002Fupgrade-jboard-panel.sh\n```\n\n常用排障：\n\n```bash\ndocker compose ps\ndocker compose logs -f app\ndocker compose --profile setup run --rm init sh -lc 'npm run db:push'\n```\n\n如果页面仍是旧版本，确认已执行 `docker compose build init app` 和 `docker compose up -d app`。如果 schema 没生效，单独运行 `npm run db:push` 对应的 setup 命令。\n\n## 反向代理与域名\n\n`NEXTAUTH_URL` 和后台“系统设置 -> 网站 URL”都应该填写面板公网域名，也就是给用户访问、并反向代理到 J-Board 的域名。不要填写 `localhost`、容器名或内网地址，否则登录回调、邮件链接、支付回跳和退出登录提示可能出现错误地址。\n\n`SUBSCRIPTION_URL` 和后台“系统设置 -> 订阅 URL”只用于生成客户端订阅链接。它可以和网站 URL 相同；如果希望单独做 Cloudflare\u002FWAF\u002F访问风控，建议使用独立订阅域名，例如 `https:\u002F\u002Fsub.example.com`，并把它也反向代理到同一个 J-Board 服务。\n\nNginx 示例：\n\n```nginx\nserver {\n  listen 80;\n  server_name panel.example.com sub.example.com;\n\n  location \u002F {\n    proxy_pass http:\u002F\u002F127.0.0.1:3000;\n    proxy_http_version 1.1;\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto $scheme;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection \"upgrade\";\n  }\n}\n```\n\n正式上线建议使用 Certbot、宝塔、1Panel、Caddy 或 CDN 配置 HTTPS。订阅域名套 Cloudflare 时，源站建议只允许 Cloudflare 回源或通过 Cloudflare Tunnel 暴露，并正确传递 `CF-Connecting-IP` \u002F `X-Forwarded-For`。如果源站允许绕过 Cloudflare 直连，订阅访问风控中的真实 IP 可能被伪造。\n\n## 后台初始化清单\n\n1. 登录 `\u002Fadmin`，进入“系统设置”，确认网站 URL 和订阅 URL。\n2. 配置 SMTP 邮件服务并点击“测试发信”。\n3. 按需要开启注册邮箱验证。忘记密码和邮箱变更也会使用 SMTP。\n4. 进入“支付配置”，填写并启用至少一种支付方式。\n5. 添加 3x-ui 节点，测试连接并同步入站。\n6. 创建代理套餐，绑定入站；或创建流媒体服务和套餐。\n7. 在节点页生成探测 Token，安装 Agent。\n8. 用普通用户注册、下单、支付、查看订阅，走一遍完整流程。\n9. 进入“订阅风控”，确认地图、IP、分析日志、人工操作按钮都能正常展示。\n\n可以展示给用户的常用入口：\n\n- 登录：`https:\u002F\u002F你的域名\u002Flogin`\n- 注册：`https:\u002F\u002F你的域名\u002Fregister`\n- 套餐商店：`https:\u002F\u002F你的域名\u002Fstore`\n- 用户中心：`https:\u002F\u002F你的域名\u002Fdashboard`\n- 订阅列表：`https:\u002F\u002F你的域名\u002Fsubscriptions`\n- 工单中心：`https:\u002F\u002F你的域名\u002Fsupport`\n\n## 邮件与邮箱验证\n\nSMTP 配置在后台“系统设置”中完成，密码会加密保存在数据库中。支持的邮件场景包括：\n\n- 注册邮箱验证，可由管理员开启或关闭。\n- 忘记密码重置链接。\n- 修改邮箱验证。\n- 管理员测试发信。\n- 风控报告发送和通知辅助。\n\n建议使用专用发信邮箱或应用专用密码。Gmail、企业邮箱和大多数 SMTP 服务都可以使用 `host + port + user + password + from` 的方式接入。生产环境请优先使用 587 STARTTLS 或服务商推荐端口。\n\n## 支付配置\n\n支付配置在后台 `\u002Fadmin\u002Fpayments` 完成，密钥会加密保存在数据库中，不写入 `.env`，也不要提交到仓库或截图外传。创建订单时，系统会根据用户选择的支付方式生成支付链接、二维码或链上收款信息；支付成功后进入 `src\u002Fservices\u002Fpayment\u002Fprocess.ts` 完成订单确认和订阅开通。\n\n| 支付方式 | 适用场景 | 必填信息 | 回调 \u002F 查询说明 |\n| --- | --- | --- | --- |\n| 易支付 | 第三方聚合支付，常用于支付宝\u002F微信通道 | API 地址、商户 ID、商户密钥、启用渠道 | 通知地址为 `https:\u002F\u002F你的域名\u002Fapi\u002Fpayment\u002Fnotify\u002Fepay`。支持 `alipay`、`wxpay` 渠道。 |\n| 支付宝当面付 | 支付宝官方扫码支付 | App ID、应用私钥、支付宝公钥、网关地址 | 通知地址为 `https:\u002F\u002F你的域名\u002Fapi\u002Fpayment\u002Fnotify\u002Falipay_f2f`，也支持订单查询兜底。 |\n| USDT TRC20 | 加密货币收款 | TRC20 钱包地址、汇率，可选 TronGrid API Key | 没有传统回调，系统按订单金额查询近期 TRC20 入账。建议配置 TronGrid API Key 提高稳定性。 |\n\n支付上线前建议：\n\n- 在支付平台后台把通知域名、回跳域名、应用网关白名单设置为公网域名。\n- 先创建低金额测试套餐，确认“创建订单 -> 支付 -> 回调\u002F查询 -> 自动开通订阅”完整可用。\n- 易支付 API 地址不要带尾部路径，例如填 `https:\u002F\u002Fpay.example.com`，系统会自动请求 `\u002Fmapi.php`、`\u002Fsubmit.php` 和 `\u002Fapi.php`。\n- 支付宝密钥可以填写纯 key 内容或 PEM 格式；系统会自动补 PEM 包装。\n- USDT TRC20 按金额匹配入账，测试时避免短时间出现多笔完全相同金额。\n\n## 节点、3x-ui 与 Agent\n\n节点接入流程：\n\n1. 在 VPS 安装并配置 3x-ui，确认面板 API 可访问。\n2. 在 3x-ui 中创建真实入站。\n3. 管理后台添加 3x-ui 节点，填写面板地址、用户名和密码。\n4. 保存后 J-Board 会登录 3x-ui 并同步入站到 `NodeInbound`。\n5. 在代理套餐中绑定已同步入站。\n6. 用户购买代理套餐后，J-Board 调用 3x-ui API 创建客户端，并保存 `NodeClient`。\n7. 订阅暂停、恢复、删除、重置访问时，同步调用 3x-ui API 更新客户端。\n8. 如需前台展示延迟、线路和节点日志风控，点击“生成探测 Token”，复制一键安装命令到节点执行。\n\nAgent 安装脚本会：\n\n- 下载 GitHub Release 中对应架构的 Agent 二进制。\n- 安装或复用 `nexttrace`。\n- 自动查找 `\u002Fusr\u002Flocal\u002Fx-ui\u002Faccess.log` 等常见 Xray access log 路径。\n- 创建 `\u002Fvar\u002Flib\u002Fjboard-agent` 和 `\u002Fvar\u002Flog\u002Fjboard`。\n- 尝试让 Agent 具有 access log 读取权限。\n- 写入 `\u002Fetc\u002Fjboard-agent.env`。\n- 停用并移除旧的 Agent systemd 服务，避免冲突。\n- 写入并启动 `jboard-agent.service`。\n\n节点机常用命令：\n\n```bash\nsystemctl status jboard-agent --no-pager -l\njournalctl -u jboard-agent -n 100 --no-pager\njournalctl -u jboard-agent -f --no-pager\njournalctl -u jboard-agent -f --no-pager | grep --line-buffered xray-log\ncat \u002Fetc\u002Fjboard-agent.env\ncat \u002Fvar\u002Flib\u002Fjboard-agent\u002Fxray-log-state.json\n```\n\n升级 Agent：\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FJetSprow\u002FJ-Board\u002Fmain\u002Fscripts\u002Fupgrade-jboard-agent.sh | bash\n```\n\n如果只想手动运行 Agent：\n\n```bash\nSERVER_URL=https:\u002F\u002Fyour-domain.com \\\nAUTH_TOKEN=后台生成的探测Token \\\n.\u002Fjboard-agent\n```\n\n更多 Agent 说明见 `agent\u002Fjboard-agent\u002FREADME.md`。\n\n## 订阅访问风控\n\nJ-Board 的订阅风控分两层。\n\n第一层是订阅 API 访问风控。用户或客户端拉取 `\u002Fapi\u002Fsubscription\u002F*` 时，系统记录真实 IP、User-Agent、国家、省\u002F地区、城市、经纬度，并按后台配置判断：\n\n- 单 IP 每小时访问次数。\n- 单订阅 token 每小时访问次数。\n- 24 小时窗口内不同城市数量。\n- 24 小时窗口内不同省\u002F地区数量。\n- 24 小时窗口内不同国家\u002F地区数量。\n\n第二层是节点真实连接风控。Agent 读取 Xray access log，将日志里的 `email: user@example.com-xxxx` 匹配到本地 `NodeClient.email`，再归属到用户和订阅。系统记录：\n\n- 真实来源 IP。\n- 真实来源 IP 的 GeoIP。\n- 入站 tag。\n- tcp\u002Fudp。\n- 样本目标域名或 IP。\n- 目标端口。\n- 聚合窗口内连接数。\n- 聚合窗口内不同目标数。\n- 首次和最近连接时间。\n\n管理员可在“系统设置 -> 订阅访问风控”中配置总开关、自动暂停开关、窗口时长、城市\u002F省\u002F国家阈值、IP\u002F订阅访问频率阈值，以及节点日志风控中的连接数和不同目标数阈值。\n\n默认规则保持为：\n\n- 24 小时内 4 个城市警告，5 个城市暂停。\n- 2 个省\u002F地区警告，3 个省\u002F地区暂停。\n- 2 个国家\u002F地区警告，3 个国家\u002F地区暂停。\n- IP 180 次\u002F小时，订阅 60 次\u002F小时。\n- 节点日志风控默认开启，连接数和不同目标数按 Agent 单次聚合窗口计算。\n\n风控事件会进入后台“订阅风控”。管理员可以：\n\n- 查看关联用户和订阅详情。\n- 查看 IP、国家、省\u002F地区、城市统计。\n- 在世界地图上查看可识别坐标点。\n- 展开分析日志，看到每条证据的 IP、时间、来源、Xray 解析详情、连接数和不同目标数。\n- 生成风险报告。\n- 选择是否发送到用户端。\n- 解除限制或保持封禁\u002F暂停。\n\n用户收到管理员发送的风险报告后，会看到全屏不可关闭的限制通知，只能新建工单联系客服，不能继续进行其他用户端操作。\n\n## GeoIP 与 Cloudflare\n\n项目内置 `data\u002FGeoLite2-City.mmdb` 作为本地 GeoIP 城市库，默认通过 `GEOIP_MMDB_PATH=data\u002FGeoLite2-City.mmdb` 读取。系统会优先使用反向代理或 CDN 提供的地理位置头，并用 MMDB 补齐缺失字段。\n\nCloudflare 场景建议在 Rules -> Settings -> Managed Transforms 开启 Add visitor location headers，让回源请求带上 `cf-ipcity`、`cf-region`、`cf-region-code` 等字段。未提供城市\u002F省份字段且 MMDB 不可用时，系统只记录 IP，不会触发地区变化规则。\n\n如果网站域名和订阅域名相同，系统只统计订阅 API 访问，不会把普通网站浏览计入订阅风控。\n\n## 备份与恢复\n\n下载 SQL 备份：\n\n```bash\ndocker compose exec -T db pg_dump -U jboard jboard > backup_$(date +%Y%m%d_%H%M%S).sql\n```\n\n后台也可通过 `\u002Fadmin\u002Fbackups` 导出或恢复数据库。恢复前务必先保存当前数据库备份。\n\n建议：\n\n- 定期备份 PostgreSQL volume。\n- 将备份加密保存。\n- 备份恢复后立即检查管理员登录、支付配置、节点密码、SMTP、订阅 URL 和 Agent 上报。\n\n## 本地开发\n\n```bash\nnpm install\ncp .env.example .env\nnpm run db:push\nnpm run db:seed\nnpm run dev\n```\n\n默认管理员账号：\n\n- 邮箱：`admin@jboard.local`\n- 密码：`admin123`\n\n常用检查：\n\n```bash\nnpx prisma generate\nnpx tsc --noEmit\nnpm run lint\nnpm run build\n```\n\n数据库变更：\n\n- 修改 `prisma\u002Fschema.prisma` 后运行 `npm run db:push`。\n- 生产 Docker 部署更新后，运行 `docker compose --profile setup run --rm init sh -lc 'npm run db:push'`。\n- 当前项目使用 `prisma db push --accept-data-loss`，上线前请确认 schema 变更不会误删重要数据。\n\nAgent 开发：\n\n```bash\ncd agent\u002Fjboard-agent\ngo test .\u002F...\nmake build-linux\nshasum -a 256 jboard-agent-linux-amd64 jboard-agent-linux-arm64 > SHA256SUMS\n```\n\n## 安全建议\n\n- 不要提交 `.env`、探测 Token、3x-ui 密码、SMTP 密码、支付密钥。\n- 数据库备份包含用户、订单、支付配置、节点凭据和邮件配置，建议加密保存并限制下载权限。\n- 生产环境不要公开 PostgreSQL 和 Redis 端口。\n- 3x-ui 面板建议限制来源 IP 或使用反向代理鉴权。\n- `ENCRYPTION_KEY` 一旦生产使用不要随意更换。\n- 管理后台账号建议使用强密码和专用邮箱。\n- 订阅域名套 CDN 时应避免源站裸露，否则真实 IP 风控可信度会下降。\n- Agent 只读 Xray access log，但日志中包含用户 IP、访问目标和 client email，应按敏感数据处理。\n\n## 常见问题\n\n### 登录、退出或邮件链接出现 localhost\n\n检查 `.env` 中的 `NEXTAUTH_URL` 和后台系统设置中的网站 URL。后台配置优先于环境变量。生产环境必须填写公网域名。\n\n### 订阅链接使用了错误域名\n\n检查 `.env` 中的 `SUBSCRIPTION_URL` 和后台系统设置中的订阅 URL。后台配置优先于环境变量。\n\n### 点击测试发信报错\n\n先确认 SMTP 是否启用、Host\u002FPort\u002FUser\u002FPassword\u002FFrom 是否正确。Gmail 等服务通常需要应用专用密码。生产环境隐藏原始异常时，可查看 `docker compose logs -f app`。\n\n### 用户不验证邮箱也能注册\n\n确认后台“注册邮箱验证”已经开启，并检查 SMTP 是否启用。邮箱验证开启后，新用户会进入待验证状态，必须通过邮件链接激活。\n\n### Agent 没有 xray-log 输出\n\n先看 Agent 是否运行：\n\n```bash\nsystemctl status jboard-agent --no-pager -l\njournalctl -u jboard-agent -n 100 --no-pager\n```\n\n再确认 access log 状态：\n\n```bash\ncat \u002Fetc\u002Fjboard-agent.env | grep XRAY\ncat \u002Fvar\u002Flib\u002Fjboard-agent\u002Fxray-log-state.json\ntail -n 50 \u002Fusr\u002Flocal\u002Fx-ui\u002Faccess.log\ngrep \"email:\" \u002Fusr\u002Flocal\u002Fx-ui\u002Faccess.log | tail -n 20\n```\n\nAgent 默认 `XRAY_LOG_START_AT_END=1`，首次启动会从文件末尾开始，只分析启动后的新连接。需要真实客户端连接节点并产生带 `email:` 的 access log，后台才会出现节点真实连接分析。\n\n### Xray client email 带后缀是否有影响\n\n没有影响。J-Board 用户邮箱可能是 `user@example.com`，Xray client email 可能是 `user@example.com-cmojtnp3`。节点日志风控用 Xray access log 里的 client email 匹配本地 `NodeClient.email`，再找到真实用户和订阅。不要手动在 3x-ui 改 client email，否则会导致日志无法归属。\n\n## 文档\n\n- `docs\u002FAPI.md`：HTTP 接口与 Server Actions 参考。\n- `docs\u002Fopenapi.yaml`：对外 HTTP 接口 OpenAPI 3.1 描述。\n- `agent\u002Fjboard-agent\u002FREADME.md`：Agent 安装、升级、日志与排障说明。\n- `AGENTS.md`：给代码协作 Agent 的仓库规则。\n\n## 请我喝杯咖啡\n\n![JsPYre9xe7W1Ad6mwPgrfuXBYJ8iy6oC.webp](https:\u002F\u002Fcdn.nodeimage.com\u002Fi\u002FXuxZ7NoLsc51fS99S6AtMB9K9ekTTQcD.webp)\n\nUSDT-TRC20: TQfaGEBdnB89V4y6R6bypZXx7Za5QfXBCi\n\nTelegram：[@JetSprow](https:\u002F\u002Ft.me\u002FJetSprow)\n","J-Board 是一个面向代理订阅售卖与流媒体共享的全栈管理面板。其核心功能包括用户管理、订单处理、支付集成、订阅交付、工单系统以及风控审查等，通过 Next.js App Router 和多种后端技术（如 PostgreSQL、Redis 和 3x-ui API）实现。该项目特别适合需要对代理服务进行商业化运营和管理的场景，能够提供从售前到售后的一站式解决方案。此外，J-Board 还具备强大的节点监测能力，通过只读 Agent 从节点侧采集延迟、路由及Xray访问日志，确保服务稳定性和安全性的同时，不干扰现有的3x-ui配置。","2026-06-11 02:51:55","CREATED_QUERY"]