178 lines
5.2 KiB
Markdown
178 lines
5.2 KiB
Markdown
# SingBox-Gopanel
|
||
|
||
`SingBox-Gopanel` 是对 `reference/Xboard` 与 `reference/LDNET-GA-Theme` 的 Go 重构版本，当前已经完成一轮后端复刻、Nebula 用户前台接入，以及 plugin 能力向统一 Go 后端的整合。
|
||
|
||
## 当前状态
|
||
|
||
- 后端主入口为 `cmd/api/main_entry.go`
|
||
- 用户前台已接入 `reference/LDNET-GA-Theme/theme/Nebula` 主题资源
|
||
- 后台已改为 Go 直接提供的统一布局，并将 plugin 页面合并到左侧栏
|
||
- Nebula 前端依赖的核心接口已补齐：
|
||
- 登录、注册、找回密码、邮箱验证码
|
||
- 用户信息、订阅、统计、节点、知识库、工单
|
||
- 活跃会话查询与撤销
|
||
- 实名认证、在线设备、IPv6 订阅 plugin API
|
||
|
||
## 目录说明
|
||
|
||
- `cmd/api`: API 启动入口
|
||
- `internal/handler`: Gin 处理器
|
||
- `internal/service`: 业务服务，包括插件、会话、配置等
|
||
- `internal/model`: GORM 数据模型
|
||
- `frontend/theme/Nebula`: 前台主题静态资源
|
||
- `frontend/admin`: 后台统一布局的静态资源
|
||
- `frontend/templates`: 用户前台与后台页面模板
|
||
- `reference`: 原始参考项目与主题/plugin 实现
|
||
- `docs/API.md`: API 文档
|
||
|
||
## 运行方式
|
||
|
||
1. 配置 `.env`
|
||
2. 启动：
|
||
|
||
```powershell
|
||
go run ./cmd/api
|
||
```
|
||
|
||
或：
|
||
|
||
```powershell
|
||
go build ./cmd/api
|
||
.\api.exe
|
||
```
|
||
|
||
默认读取 `.env` 中的 MySQL、Valkey/Redis 与应用配置。
|
||
|
||
## 安装脚本
|
||
|
||
仓库已提供两个 Linux 脚本：
|
||
|
||
- `scripts/build_install.sh`：在仓库当前目录下载 Go 工具链并编译 `api`
|
||
- `scripts/install.sh`：针对自动化构建产物目录执行安装
|
||
|
||
从源码构建：
|
||
|
||
```bash
|
||
bash scripts/build_install.sh
|
||
```
|
||
|
||
从自动化构建产物安装：
|
||
|
||
```bash
|
||
cd package
|
||
sudo bash ./install.sh --install-dir /opt/singbox-gopanel --run-user root
|
||
```
|
||
|
||
脚本会执行这些步骤：
|
||
|
||
- 在 `/opt` 下创建安装目录及其 `frontend`、`docs` 子目录
|
||
- 复制 `api`、`frontend`、`docs`、`README.md` 与 `.env.example`
|
||
- 在安装目录生成 `.env`
|
||
- 安装并重启 systemd 服务
|
||
|
||
默认 service 名称是 `singbox-gopanel`，可通过 `--service-name` 修改。
|
||
|
||
## Gitea Actions
|
||
|
||
仓库已新增 Gitea workflow：
|
||
|
||
- `.gitea/workflows/build.yml`
|
||
|
||
当前 workflow 会：
|
||
|
||
- 执行 `go build ./cmd/api`
|
||
- 执行 `go build ./...`
|
||
- 构建 Linux `amd64` / `arm64` 二进制
|
||
- 按平台输出目录化制品，例如 `singbox-gopanel-linux-amd64/`
|
||
- 将二进制、`frontend`、`docs`、`.env.example`、`install.sh` 直接作为 artifact 上传
|
||
- 不再额外生成 `zip` / `tar.gz`
|
||
|
||
## 当前远端开发环境
|
||
|
||
以下信息基于 2026-04-17 对远端环境的实际核对：
|
||
|
||
- 开发服务器：`10.32.100.3`
|
||
- SSH：使用仓库内 `AIAgentKey.pem`
|
||
- 数据库：`xboard`
|
||
- 数据库密码：`11223456`
|
||
- 当前 `v2_settings.secure_path`：`helloadmin`
|
||
- 当前 `v2_settings.app_name`：`LDNET-GA`
|
||
- 当前 `real_name_verification`、`user_online_devices`、`user_add_ipv6_subscription` 三个 plugin 均为启用状态
|
||
|
||
## 前台与后台页面
|
||
|
||
- 用户前台：`/`
|
||
- 用户前台备用入口：`/dashboard`
|
||
- 后台入口：`/{secure_path}`
|
||
- 远端当前值是 `/helloadmin`
|
||
|
||
后台左侧栏已整合：
|
||
|
||
- 总览
|
||
- 实名认证
|
||
- 在线设备
|
||
- IPv6 订阅
|
||
- Plugin 集成状态
|
||
|
||
## Plugin 集成结论
|
||
|
||
### 已完成
|
||
|
||
- `RealNameVerification`
|
||
- 用户查询状态
|
||
- 用户提交实名信息
|
||
- 管理端记录查询、通过、驳回、重置、批量同步、批量通过
|
||
- `auto_approve`、`allow_resubmit_after_reject`、`enforce_real_name`、`verified_expiration_date` 已接入
|
||
|
||
- `UserOnlineDevices`
|
||
- 用户在线 IP 查询
|
||
- 管理端用户在线设备监控
|
||
- 与新的活跃会话能力联动输出 `session_overview`
|
||
|
||
- `UserAddIPv6Subscription`
|
||
- 用户资格检查
|
||
- 手动启用
|
||
- IPv6 子账号密码同步
|
||
- 运行时影子账号自动同步
|
||
|
||
### 仍需后续完整订单流配合
|
||
|
||
- `UserAddIPv6Subscription` 的“订单完成后立即自动创建 IPv6 子账号”这一点，仍然依赖后续订单生命周期重构完全落地后再补最终钩子。
|
||
|
||
## 已完成的主要改动
|
||
|
||
- 新增 Nebula 前台页面模板与静态资源接入
|
||
- 新增统一后台页面与左侧栏 plugin 入口
|
||
- 补充知识库、工单、活跃会话相关接口
|
||
- 补充 token 快速登录、邮箱验证码、找回密码接口
|
||
- 为 JWT 登录补充基于缓存的会话跟踪与撤销能力
|
||
- 调整实名插件逻辑，贴近参考配置行为
|
||
- 输出 plugin 集成状态接口，便于后台与文档统一核对
|
||
|
||
## 验证
|
||
|
||
已完成：
|
||
|
||
- `go build ./cmd/api`
|
||
- `go build ./...`
|
||
|
||
说明：
|
||
|
||
- 本地编译已通过
|
||
- 本地实际连远端 DB/Valkey 的完整页面联调仍建议在目标服务器或等价网络环境下继续验证
|
||
## 2026-04 parity addendum
|
||
|
||
This pass added another backend parity sweep against `reference/Xboard`.
|
||
|
||
Added in this round:
|
||
|
||
- passport quick-login URL, mail-link compatibility, and invite PV tracking
|
||
- user notice, invite, traffic-log, order, coupon, Telegram bot info, Stripe public key, and quick-login compatibility endpoints
|
||
- admin config save support backed by `v2_settings`
|
||
- missing GORM models for `v2_notice`, `v2_invite_code`, `v2_payment`, `v2_commission_log`, `v2_stat_user`, and `v2_coupon`
|
||
|
||
Validation after the changes:
|
||
|
||
- `go build ./cmd/api`
|
||
- `go build ./...`
|