rose_cat707
c26b06f1cc
Go 控制面（SQLite + REST API）嵌入 Mihomo 数据面，Vue 3 多语言 Web 管理台。 含订阅/节点/规则/出站/监控/日志、OpenAPI、API Key、Gitea Actions CI 与开源文档； CI 使用 ubuntu-latest runner，Go/Docker 步骤走国内镜像与 shell，避免 GitHub 下载超时。 Co-authored-by: Cursor <cursoragent@cursor.com>
296 lines
8.6 KiB
Markdown
296 lines
8.6 KiB
Markdown
# Prism
|
||
|
||
HTTP / SOCKS5 代理网关，带 Web 管理台。控制面自研（Go + SQLite），数据面嵌入 [Mihomo](https://github.com/MetaCubeX/mihomo)。
|
||
|
||
**源码仓库：** [git.rc707blog.top/rose_cat707/Prism](https://git.rc707blog.top/rose_cat707/Prism)
|
||
|
||
管理台支持**简体中文、繁体中文、英文**三种界面语言，可在「系统设置 → 显示语言」中随时切换。
|
||
|
||
## 功能概览
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| 订阅管理 | Clash YAML、节点链接、自动识别；定时拉取与热重载 |
|
||
| 代理节点 | 订阅/手动节点、国家标签、延迟测速、导入导出 |
|
||
| 出站管理 | 默认出站、策略组切换、国家 url-test 池 |
|
||
| 路由规则 | 手动高优先级规则、合成预览、命中测试、导入导出 |
|
||
| 监控大盘 | 实时速率、域名/节点流量、连接趋势 |
|
||
| 日志 | 请求日志、运行日志、审计日志（分页，单页最多 500 条） |
|
||
| 系统设置 | 端口、认证、Geo 数据、API Key、界面语言 |
|
||
| OpenAPI | `/api/docs` 交互文档，`/api/v1/openapi.json` |
|
||
|
||
## 架构
|
||
|
||
```
|
||
客户端 → Mihomo 入站 (HTTP/SOCKS5) → 规则引擎 → 出站节点
|
||
↑
|
||
Prism 控制面 (配置合成 / REST API / Vue UI)
|
||
↓
|
||
SQLite + 内存缓存
|
||
```
|
||
|
||
## 快速开始（开发）
|
||
|
||
### 依赖
|
||
|
||
- Go 1.25+（见 `go.mod`）
|
||
- Node.js 20+（仅开发/构建前端）
|
||
|
||
依赖镜像（已写入 `go.env`、`web/.npmrc`，国内网络友好）：
|
||
|
||
- Go：`GOPROXY=https://goproxy.cn,direct`
|
||
- npm：`registry=https://registry.npmmirror.com`
|
||
|
||
海外用户可将 `GOPROXY` 改为 `https://proxy.golang.org,direct`，npm 使用默认 registry 即可。
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
# 终端 1：后端
|
||
make run
|
||
|
||
# 终端 2：前端（Vite 代理 /api → :8080）
|
||
make dev-web
|
||
```
|
||
|
||
访问 http://localhost:5173 ，默认密码 `admin`（**首次登录后请立即修改**）。
|
||
|
||
```bash
|
||
make test # 运行单元测试
|
||
make build # 构建 dist/prism
|
||
```
|
||
|
||
## 部署方案
|
||
|
||
### 方案一：二进制部署（推荐 VPS / 裸机）
|
||
|
||
适合已有 Linux 服务器、希望资源占用最小的场景。
|
||
|
||
```bash
|
||
# 1. 构建（含前端静态资源嵌入）
|
||
make build
|
||
|
||
# 2. 准备数据目录
|
||
mkdir -p /opt/prism/data
|
||
|
||
# 3. 前台运行（调试）
|
||
./dist/prism -data /opt/prism/data
|
||
|
||
# 4. 生产建议使用 systemd（示例）
|
||
```
|
||
|
||
`/etc/systemd/system/prism.service` 示例：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Prism Proxy Gateway
|
||
After=network-online.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=prism
|
||
WorkingDirectory=/opt/prism
|
||
ExecStart=/opt/prism/prism -data /opt/prism/data
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
**端口映射（默认）**
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| 管理 API / Web UI | 8080 | 浏览器访问管理台 |
|
||
| HTTP 代理 | 7890 | 客户端 HTTP 代理 |
|
||
| SOCKS5 代理 | 7891 | 客户端 SOCKS5 代理 |
|
||
| Mihomo 内部 API | 9090 | 仅 127.0.0.1，勿对外暴露 |
|
||
|
||
代理端口可在管理台「系统设置」修改并保存后重载内核；**管理 API 端口**修改后需重启进程。
|
||
|
||
**反向代理（可选）**
|
||
|
||
若希望通过域名 + HTTPS 访问管理台，可在前面加 Nginx/Caddy，将 `/` 与 `/api` 反代到 `127.0.0.1:8080`。务必启用访问控制（VPN、IP 白名单或强密码 + 关闭公网入站代理端口）。
|
||
|
||
### 方案二：Docker 单容器
|
||
|
||
适合 NAS、面板一键部署、多架构（amd64/arm64）。
|
||
|
||
镜像由 Gitea Actions 自动构建，发布到 Gitea Container Registry：
|
||
|
||
```
|
||
git.rc707blog.top/rose_cat707/prism:{tag}
|
||
```
|
||
|
||
| Tag | 说明 |
|
||
|-----|------|
|
||
| `latest` | `main` / `master` 分支最新构建 |
|
||
| `sha-xxxxxxx` | 对应 commit 短 SHA |
|
||
| `v1.2.3` | 推送 Git tag `v1.2.3` 时发布 |
|
||
|
||
```bash
|
||
# 本地构建
|
||
make docker-build
|
||
|
||
# 拉取 CI 构建镜像
|
||
docker login git.rc707blog.top
|
||
docker pull git.rc707blog.top/rose_cat707/prism:latest
|
||
|
||
docker run -d --name prism \
|
||
--restart unless-stopped \
|
||
-p 8080:8080 \
|
||
-p 7890:7890 \
|
||
-p 7891:7891 \
|
||
-v prism-data:/app/data \
|
||
git.rc707blog.top/rose_cat707/prism:latest
|
||
```
|
||
|
||
**本地多架构构建并推送**
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `REGISTRY` | `git.rc707blog.top` | Gitea 实例域名（Container Registry 与代码仓库同域） |
|
||
| `OWNER` | `rose_cat707` | 镜像 owner |
|
||
| `IMAGE` | `prism` | 镜像名 |
|
||
| `TAG` | `latest` | 标签 |
|
||
| `PLATFORM` | `linux/amd64,linux/arm64` | 目标架构 |
|
||
|
||
```bash
|
||
make docker-push
|
||
# 或
|
||
REGISTRY=git.rc707blog.top OWNER=rose_cat707 TAG=v1.0.0 ./scripts/docker-build-push-multiarch.sh
|
||
```
|
||
|
||
### 方案三：Docker Compose
|
||
|
||
仓库已包含 `docker-compose.yml`：
|
||
|
||
```bash
|
||
docker login git.rc707blog.top
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
数据持久化在 `./data`，升级镜像时保留卷即可。
|
||
|
||
## 数据目录
|
||
|
||
`-data` 指定数据目录（默认 `./data`）：
|
||
|
||
```
|
||
data/
|
||
├── prism.db # SQLite：订阅、节点、规则、设置、日志
|
||
└── geo/ # Country.mmdb、geoip.dat、geosite.dat
|
||
```
|
||
|
||
首次使用含 `GEOIP`/`GEOSITE` 规则时，可在「系统设置 → Geo 数据」一键下载，或手动放入 `data/geo/`。
|
||
|
||
## 使用攻略（简要）
|
||
|
||
### 1. 首次登录
|
||
|
||
1. 打开 `http://<主机>:8080`
|
||
2. 默认密码 `admin`，登录后进入「系统设置」修改密码
|
||
3. 按需切换「显示语言」
|
||
|
||
### 2. 添加订阅
|
||
|
||
1. 「订阅管理」→「添加订阅」
|
||
2. 类型选 **自动识别**（兼容 Clash YAML、Base64 链接、短链）
|
||
3. 保存后自动拉取节点并重载内核
|
||
|
||
### 3. 配置出站
|
||
|
||
1. 「出站管理」设置**默认出站**（未命中规则时生效）
|
||
2. 在策略组中切换当前节点；国家池为自动测速选最快
|
||
|
||
### 4. 配置规则
|
||
|
||
1. 「路由规则」添加手动规则（优先级高于订阅规则）
|
||
2. 可将域名指向 `country:HK` 等国家池，或 `DIRECT` / `PROXY`
|
||
3. 使用「规则命中测试」验证 URL 走向
|
||
|
||
### 5. 客户端接入
|
||
|
||
| 类型 | 地址 | 默认 |
|
||
|------|------|------|
|
||
| HTTP 代理 | `<服务器IP>:7890` | 无认证（可在设置中启用） |
|
||
| SOCKS5 | `<服务器IP>:7891` | 同上 |
|
||
|
||
本机 `127.0.0.1` 访问代理可免认证（若已配置入站认证）。
|
||
|
||
### 6. API 与自动化
|
||
|
||
- 交互文档：`http://<主机>:8080/api/docs`
|
||
- 登录获取 Token：`POST /api/v1/auth/login`
|
||
- 或在「系统设置」申请 **API Key**，请求头：
|
||
- `Authorization: Bearer <key>` 或
|
||
- `X-API-Key: <key>`
|
||
- 修改配置后：`POST /api/v1/system/reload` 热重载内核
|
||
|
||
### 7. 日常运维
|
||
|
||
| 操作 | 位置 / API |
|
||
|------|------------|
|
||
| 查看流量与连接 | 监控大盘 |
|
||
| 节点测速 | 代理节点 → 全部测速 |
|
||
| 查看请求明细 | 请求日志 |
|
||
| 更新 Geo | 系统设置 → Geo 数据 |
|
||
| 重载配置 | 系统设置 → 重载内核 |
|
||
|
||
## 订阅类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `auto` | 自动识别（推荐） |
|
||
| `clash` | Clash / Mihomo YAML |
|
||
| `links` | Base64 或纯文本节点链接 |
|
||
|
||
## API 前缀
|
||
|
||
REST API：`/api/v1`
|
||
认证：`Authorization: Bearer <token>` 或 API Key。
|
||
|
||
主要端点：`/dashboard`、`/subscriptions`、`/proxies`、`/rules`、`/settings`、`/traffic-logs`、`/logs`、`/system/reload`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
cmd/prism/ # 进程入口
|
||
internal/
|
||
api/ # HTTP 层（按域拆分 handlers_*.go）
|
||
settings/ # 设置键名、展示/提交规范化、语言
|
||
store/ # SQLite 与仓储
|
||
service/ # 编排与热重载
|
||
configbuilder/ # Mihomo YAML 合成
|
||
subscription/ # 订阅拉取解析
|
||
web/ # Vue 3 管理台
|
||
src/i18n/ # 多语言资源
|
||
src/views/ # 页面
|
||
src/styles/ # 设计系统 theme.css
|
||
.gitea/workflows/ # Gitea Actions CI
|
||
```
|
||
|
||
## CI / 自动发布
|
||
|
||
推送代码到 `main` / `master` 或 tag `v*` 时，Gitea Actions 会：
|
||
|
||
1. 运行 `go test ./...`
|
||
2. 构建 `linux/amd64` + `linux/arm64` 镜像
|
||
3. 推送到 `git.rc707blog.top/rose_cat707/prism`
|
||
|
||
维护者需：① 在线 runner（标签含 `ubuntu-latest`）；② Secret `REGISTRY_TOKEN`。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
## 贡献与安全
|
||
|
||
- [CONTRIBUTING.md](CONTRIBUTING.md) — 开发环境、CI 配置、提交规范
|
||
- [SECURITY.md](SECURITY.md) — 漏洞报告与部署安全建议
|
||
- [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) — 第三方组件与许可
|
||
|
||
## 许可
|
||
|
||
Prism 控制面代码采用 [MIT License](LICENSE)。
|
||
|
||
嵌入的 [Mihomo](https://github.com/MetaCubeX/mihomo) 内核采用 **GPL-3.0 OR MIT** 双重许可。分发二进制或容器镜像时，请保留相关版权声明并遵守 Mihomo 及全部依赖的许可条款。详见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
|