Prism/CONTRIBUTING.md

贡献指南

感谢关注 Prism！本仓库托管于 git.rc707blog.top。

开发环境

依赖

• 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 即可。

启动

# 终端 1：后端
make run

# 终端 2：前端（Vite 代理 /api → :8080）
make dev-web

浏览器访问 http://localhost:5173 ，默认密码 admin。

测试与构建

make test   # 运行 Go 单元测试
make build  # 构建含前端的单二进制 dist/prism

提交规范

• 一个 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 文档。

Runner 配置

CI 使用 runs-on: ubuntu-latest（须与 Runners 页「标签」列一致）。

1. Settings → Actions → Runners 确认 runner 在线，标签含 ubuntu-latest
2. 标签映射的 job 镜像须含 Node.js（否则 actions/checkout 会报 node not in PATH）
3. 构建镜像：runner 须挂载 /var/run/docker.sock（见 .gitea/act-runner/README.md）
4. CI 使用 shell 安装 Go（阿里云 / golang.google.cn 镜像），避免 setup-go 从 GitHub 下载超时

目录结构

cmd/prism/           进程入口
internal/api/        HTTP 层、OpenAPI、嵌入静态资源
internal/store/      SQLite 与迁移
internal/service/    业务编排
internal/configbuilder/  Mihomo YAML 合成
web/                 Vue 3 管理台
.gitea/workflows/    CI 工作流

许可

提交代码即表示你同意在 MIT License 下授权你的贡献。嵌入的 Mihomo 内核遵循其自身许可，见 THIRD-PARTY-NOTICES.md。