first commit

README.md

@@ -0,0 +1,177 @@
+# 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 ./...`