# 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 ./...`