rose_cat707
024c15a836
Go 控制面（SQLite + REST API）嵌入 Mihomo 数据面，Vue 3 多语言 Web 管理台。 含订阅/节点/规则/出站/监控/日志、OpenAPI、API Key、Gitea Actions CI 与开源文档。 Co-authored-by: Cursor <cursoragent@cursor.com>
95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# 贡献指南
|
||
|
||
感谢关注 Prism！本仓库托管于 [git.rc707blog.top](https://git.rc707blog.top/rose_cat707/Prism)。
|
||
|
||
## 开发环境
|
||
|
||
### 依赖
|
||
|
||
- Go 1.25+（见 `go.mod`）
|
||
- Node.js 20+（仅前端开发/构建）
|
||
|
||
国内网络可使用仓库内已配置的镜像：
|
||
|
||
- Go：`go.env` → `GOPROXY=https://goproxy.cn,direct`
|
||
- npm：`web/.npmrc` → `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 # 运行 Go 单元测试
|
||
make build # 构建含前端的单二进制 dist/prism
|
||
make docker-build # 本地 Docker 镜像
|
||
```
|
||
|
||
## 提交规范
|
||
|
||
- 一个 PR 聚焦一个主题，避免混合无关重构
|
||
- 涉及 API 变更时同步更新 `internal/api/openapi/spec.yaml`
|
||
- 涉及 UI 变更请参考 `UI-DESIGN-SYSTEM.md`
|
||
- 确保 `go test ./...` 通过
|
||
|
||
## CI / 镜像发布
|
||
|
||
仓库使用 **Gitea Actions**（`.gitea/workflows/ci.yml`）：
|
||
|
||
| 触发 | 行为 |
|
||
|------|------|
|
||
| Pull Request | 仅运行 `go test ./...` |
|
||
| 推送到 `main` / `master` | 测试 + 构建并推送 `latest` 与 `sha-xxxxxxx` 镜像 |
|
||
| 推送 tag `v*` | 测试 + 额外推送版本 tag 镜像 |
|
||
|
||
镜像发布到 Gitea Container Registry：
|
||
|
||
```
|
||
git.rc707blog.top/{owner}/prism:{tag}
|
||
```
|
||
|
||
### 维护者：配置 CI Secret
|
||
|
||
在仓库 **Settings → Secrets → Actions** 添加：
|
||
|
||
| Secret | 说明 |
|
||
|--------|------|
|
||
| `REGISTRY_TOKEN` | 具有 `write:package` 权限的 Personal Access Token |
|
||
|
||
> **注意：** Secret 名称不能以 `GITEA_` 或 `GITHUB_` 开头（Gitea 保留前缀），因此使用 `REGISTRY_TOKEN` 而非 `GITEA_TOKEN`。
|
||
|
||
> Gitea Actions 的 job token 暂不支持直接推送软件包，需使用 PAT。见 [Gitea 文档](https://docs.gitea.com/usage/actions/comparison#package-repository-authorization)。
|
||
|
||
### Runner 要求
|
||
|
||
- 已注册 act_runner，且挂载 Docker socket（或 DinD）
|
||
- `runs-on: ubuntu-latest` 标签可用
|
||
- 支持 `linux/amd64` + `linux/arm64` 多架构构建（需 QEMU）
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
cmd/prism/ 进程入口
|
||
internal/api/ HTTP 层、OpenAPI、嵌入静态资源
|
||
internal/store/ SQLite 与迁移
|
||
internal/service/ 业务编排
|
||
internal/configbuilder/ Mihomo YAML 合成
|
||
web/ Vue 3 管理台
|
||
.gitea/workflows/ CI 工作流
|
||
```
|
||
|
||
## 许可
|
||
|
||
提交代码即表示你同意在 [MIT License](LICENSE) 下授权你的贡献。嵌入的 Mihomo 内核遵循其自身许可，见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
|