renjue
fe8ea784d0
CI / docker (push) Successful in 2m54s
Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
3.0 KiB
Markdown
97 lines
3.0 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
|
||
```
|
||
|
||
## 提交规范
|
||
|
||
- 一个 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 配置
|
||
|
||
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](.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](LICENSE) 下授权你的贡献。嵌入的 Mihomo 内核遵循其自身许可，见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
|