diff --git a/docs/环境与部署/CI配置指南.md b/docs/环境与部署/CI配置指南.md index 72834f92..c1a5186b 100644 --- a/docs/环境与部署/CI配置指南.md +++ b/docs/环境与部署/CI配置指南.md @@ -50,12 +50,34 @@ ENABLED = true ```ini [actions] ENABLED = true -; 可选:限制单仓库并发任务数,防 runner 被占满 -DEFAULT_ACTIONS_URL = https://gitea.com ``` 改完 **重启 Gitea 服务**(Docker:`docker restart <容器名>`;二进制:重启进程)。 +### 1.2.1 `DEFAULT_ACTIONS_URL` 是什么(**容易搞反**) + +它**不是你的 Gitea 地址**,而是控制 **`uses: actions/checkout@v4` 这类 action 从哪里下载**: + +| 取值 | 行为 | +|---|---| +| **不配(默认)** | 从 **[github.com](https://github.com)** 拉取 action | +| `self` | 从**你自己的 Gitea 实例**拉取(要求 action 已镜像进你的实例) | +| 具体 URL(如 `https://gitea.com`) | 从该地址拉取 | + +> ⚠️ **不要把你的实例域名写进去当普通 URL**——要"从自己实例拉"就用关键字 **`self`**; +> 且**写了 `self` 还得先把 action 镜像进自己实例**,否则 `actions/checkout` 依然拉不到。 + +**按你的网络环境选择**: + +| 场景 | 配置 | +|---|---| +| 服务器**能**访问 github.com | **什么都不配**(默认走 github.com,最省事) | +| 内网,**不能**访问 github.com | 建议**改用零依赖写法**(见 §4.3 方案 3),`DEFAULT_ACTIONS_URL` 配不配都行;
若坚持用 `actions/checkout@v4`,则需 `DEFAULT_ACTIONS_URL = self` **且**把该 action 镜像进实例 | + +> Gitea 官方 FAQ 原文:*"From `https://github.com` by default, or from your own instance +> when `[actions].DEFAULT_ACTIONS_URL` is `self`."* 使用别处 action 也可在 workflow 里直接写全路径: +> `uses: https://gitea.com/owner/repo@ref` / `uses: self:owner/repo@ref`。 + ### 1.3 验证 浏览器打开仓库地址,顶部/侧栏应出现 **Actions** 标签页。 @@ -215,13 +237,13 @@ on: ### 4.3 内网无公网时的 action 拉取(重要) -workflow 用了 `actions/checkout@v4`。Gitea 默认从 **gitea.com** 代理拉取官方 action; -若实例不通外网,会在 checkout 步骤卡住/失败。三种处置: +workflow 用了 `actions/checkout@v4`。**默认从 `github.com` 拉取**(见 §1.2.1);实例不通 +github.com 会在 checkout 步骤卡住/失败。三种处置: -1. **开代理**:在 Gitea `app.ini` 配 `[actions] DEFAULT_ACTIONS_URL = https://gitea.com` - 并确保服务器能访问该域名; -2. **镜像**:改 `DEFAULT_ACTIONS_URL` 指向可达的 action 镜像; -3. **零依赖**:把 checkout 换成纯 git 命令(不依赖任何 action): +1. **镜像到自有实例**:`DEFAULT_ACTIONS_URL = self`,**并先把 `actions/checkout` 导入你自己的 Gitea**; +2. **指向可达镜像**:`DEFAULT_ACTIONS_URL` 指向某个能访问的 action 站(或在 workflow 里 + 直接写全路径 `uses: https:///owner/repo@ref`); +3. **零依赖**(内网最稳,推荐):把 checkout 换成纯 git 命令,不依赖任何 action: ```yaml - name: Checkout @@ -233,7 +255,8 @@ workflow 用了 `actions/checkout@v4`。Gitea 默认从 **gitea.com** 代理拉 git checkout $env:GITHUB_SHA ``` -> 方案 3 无需任何外部 action,内网最稳;代价是失去 checkout 的缓存优化。 +> 方案 3 无需任何外部 action 与任何 `DEFAULT_ACTIONS_URL` 配置;代价是失去 checkout 的缓存优化。 +> 参考:Gitea FAQ「Where will the runner download scripts when using actions such as `actions/checkout@v4`?」 --- @@ -290,4 +313,5 @@ workflow 用了 `actions/checkout@v4`。Gitea 默认从 **gitea.com** 代理拉 | 日期 | 变更 | |---|---| +| 2026-10-01 | **修正 `DEFAULT_ACTIONS_URL` 说明**(原 §1.2 示例误导):新增 §1.2.1 明确它控制的是 **action 下载源**(默认 `github.com`;`self` = 从自己实例拉且需先镜像 action),**不是填自己的 Gitea 地址**;§4.3 同步修正(原文误写"gitea.com 代理"),并补零依赖写法为内网首选。依据:Gitea 官方 FAQ + config-cheat-sheet | | 2026-10-01 | 初版:Gitea Actions 配置全流程(服务端开关 / Windows runner 注册 / runner 软件环境 / workflow 位置与触发 / 内网 action 拉取 / 端到端验证清单 / 故障排查 / 日常维护) |