企业官网建设流程全解析

• 后端
• 开发工具

本指南聚焦 Weblate 与代码托管平台（GitHub、GitLab、Gitea、Bitbucket、Azure DevOps、Pagure 等）之间的 HTTPS + 访问令牌（Access Token）接入方案。你将掌握如何在组件设置中填入带令牌的仓库 URL、按读/写需求正确分配令牌权限、判断何时需要配置推送地址，以及 Weblate 底层如何校验 URL 与防护私有地址，从而安全高效地让 Weblate 克隆并回推翻译仓库。

何时使用 HTTPS 令牌接入：最简单仓库方案

对于单个私有仓库，当代码托管平台支持基于 HTTPS 的 Git 访问时，使用访问令牌是通常最简单的配置方式。相比 SSH 专用用户方案，它无需在平台侧管理 SSH 公钥，只需把「平台要求的用户名 + 令牌」直接拼进仓库 URL，填入组件的 Source code repository（source 仓库） 字段即可。

该建议来自 Weblate 官方代码托管集成文档中被多处复用的核心片段 code-hosting-https-repository-access.rst，它同时被引入到 docs/admin/code-hosting.rst 中 GitHub（第 222 行）、GitLab（第 462 行）、Gitea/Forgejo/Codeberg（第 551 行）、Bitbucket（第 629 行）、Azure DevOps（第 724 行）、Pagure（第 783 行）、Gitee（第 839 行）等多个平台的「Repository access」小节，属于跨平台通用的接入范式。

从源码看，weblate/vcs/git.py 的configure_remote会把组件配置中的拉取 URL（pull_url）写入 Git 的remote "origin".url，把推送 URL（push_url）写入pushurl（为空则移除），因此 HTTPS 令牌 URL 与 SSH URL 在 Weblate 内部走的是同一套远端配置机制，令牌方式只是改变了 URL 的形态。

令牌权限：读用于克隆，写用于推送

令牌的权限要求遵循最小权限原则，核心规则如下：

• 读（read）权限：必须授予，用于 Weblate 克隆（clone）仓库并拉取更新；
• 写（write）权限：仅当需要 Weblate 直接推送（push）翻译回仓库时才需要授予；
• 如果选择了GitHub、GitLab、Gitea等平台专属 VCS 后端（用于创建 Pull Request / Merge Request），还需要在 Weblate 设置中单独配置API 凭据（如 GITHUB_CREDENTIALS），这些凭据与 Git 仓库 URL 中的令牌相互独立、分开管理。

换言之，URL 中的令牌只负责 Git 传输层的鉴权；若工作流是「创建 PR 而非直推」，API 凭据承担的是平台 REST API 层的鉴权，二者缺一不可。该规则同样见 code-hosting-ssh-repository-access.rst，其中明确指出：使用平台专属 VCS 后端创建 PR/MR 时，「Provider API credentials are still needed…configured separately from the Git repository URL」。

各大平台的 URL 拼写规范

令牌 URL 的通用形态是https://<用户名>:<令牌>@<主机>/<路径>.git，但不同平台对「用户名」位置的要求存在差异，下面按平台逐一说明。

GitHub：https://username:token@github.com/owner/repo.git

• 在 GitHub 创建个人访问令牌（Personal Access Token）后，将其与用户名拼进仓库 URL：https://username:token@github.com/owner/repo.git；
• 该方式适合刚开始使用 Weblate或只处理单个仓库的场景；
• 若后续需要为 GitHub 组件创建 Pull Request，可改用 Hosted Weblate GitHub App（托管服务）或配置GITHUB_CREDENTIALS（自托管）走平台后端，而非继续依赖 URL 内嵌令牌。

GitLab：用户名位置必须非空

• 使用个人访问令牌时，URL 中应填真实用户名：https://user:personal_access_token@gitlab.com/example/example.git；
• 使用**项目访问令牌（project access token）**时，用户名可以填任意非空值：https://example:project_access_token@gitlab.com/example/example.git；
• GitLab 令牌还需要授予write_repositoryscope 才能推送；项目访问令牌则要求用户具备Developer角色方可推送（见 docs/admin/code-hosting.rst）；
• 注意：GitLab 各版本对项目访问令牌 URL 中用户名的要求曾多次变化（旧版本要求项目名或机器人用户名），如不确定请对照你所用 GitLab 版本的官方说明。

Gitea / Forgejo / Codeberg、Bitbucket、Pagure、Gitee

这些平台的仓库访问小节均直接复用同一片段，即采用「HTTPS + 访问令牌」的通用做法：将平台要求的用户名与令牌填入component-repo，令牌同样遵循「读可克隆、写可推送」的权限要求（见 docs/admin/code-hosting.rst、L616-L638、L770-L788、L831-L844）。

Azure DevOps

直接使用 Azure Repos 页面显示的HTTPS clone URL填入组件仓库地址，无需手工改写 URL（见 docs/admin/code-hosting.rst）；令牌的读写权限按上文原则配置。

何时配置推送 URL（component-push）

片段强调：只有在以下两种情况才需要配置 Repository push URL（component-push）：

1. Weblate 需要直接推送翻译改动回远端仓库；
2. 所选择的工作流本身要求提供推送 URL（例如 Gerrit 评审、或从分支创建 PR/MR 的场景）。

若组件不配置component-push，Weblate 只会克隆（拉取）仓库而不会直推，翻译成果需要通过平台后端（PR/MR）或人工合并回流。关于「何时推、怎么推」的完整决策表见 docs/admin/code-hosting.rst 的 Pushing changes from Weblate 小节，核心组合如下：

*当component-repo本身支持推送时，该处可以为空。

另外，Weblate 支持在每次提交时自动推送（component-push_on_commit 默认开启）；若不想自动推送，可在「Repository maintenance」界面手动推送，或通过命令行工具wlc push触发。

底层实现与安全机制

URL 凭据解析

在 weblate/vcs/git.py 中，Weblate 解析仓库 URL 时会提取netloc中@之前的userinfo（即用户名:令牌段），并在处理跳转等场景时将其保留到目标 URL 上，确保带凭据的令牌 URL 在内部流转时不丢失鉴权信息。

支持的 URL 协议

Weblate 默认只允许https与ssh两种协议，由 VCS_ALLOW_SCHEMES（自 5.15 起）控制；file协议与裸文件系统路径因安全原因被禁用——它们可能让组件编辑者访问服务器本地文件系统上的仓库。Docker 部署可通过环境变量 WEBLATE_VCS_ALLOW_SCHEMES 覆盖。

私有地址防护

VCS_RESTRICT_PRIVATE（自 5.17 起，默认开启）会拒绝指向内网或非公网地址的仓库 URL，除非目标主机被加入VCS_ALLOW_HOSTS或VCS_PRIVATE_ALLOWLIST白名单；解析失败的主机名同样会被拒绝。这对 HTTPS 令牌接入有两层实际影响：

• 仓库主机名必须能从 Weblate 服务器正常解析（DNS）；
• 若是部署在可信内网中的私有仓库，需由实例管理员将主机名加入白名单，否则令牌 URL 会在校验阶段直接被拒；
• 对于 Git over HTTPS/SSH，Weblate 还会把 VCS 命令绑定到校验通过的地址上，并且默认不自动跟随跨主机重定向——跳转到其他主机或协议的仓库 URL 需要手动配置（见 docs/vcs.rst 的 Troubleshooting repository URLs 小节）。

与 SSH 专用用户方案的取舍

片段推荐令牌方式用于「单仓库、最简单」场景；当涉及多个仓库时，官方更建议采用 SSH + 专用代码托管用户方案（code-hosting-ssh-repository-access.rst）：把 Weblate 公钥挂到专用用户下，用git@example.com:group/project.git形式的 SSH URL 访问，从而规避许多平台「同一把公钥只能绑定一次」的限制，也避免把个人/项目/API 令牌长期内嵌在 URL 中。两种方案对自托管与 Hosted Weblate 的适用边界，可对照 docs/vcs.rst 的 Accessing repositories 章节。

接入自检清单

完成 HTTPS 令牌接入后，建议逐项核对：

1. URL 形态：确认https://user:token@host/path.git中用户名、令牌均已正确填充，且平台对用户名位置的要求已满足（尤其 GitLab）；
2. 令牌权限：仅克隆给读权限；需要直推时再补充写权限；选择平台 VCS 后端创建 PR/MR 时，另行配置对应 API 凭据；
3. 推送地址：仅当需要直推或工作流要求时配置component-push，并确认push_branch是否应留空（fork 流程）或填目标分支；
4. 连通性：仓库主机名可从 Weblate 服务器解析；内网仓库需管理员加入VCS_ALLOW_HOSTS白名单；
5. 协议策略：确认VCS_ALLOW_SCHEMES允许https，且 URL 未被VCS_RESTRICT_PRIVATE拦截（看组件诊断告警即可确认）。

遵循上述要点，即可在最小配置成本下让 Weblate 安全、稳定地通过 HTTPS 令牌接入私有翻译仓库，并为后续扩展 PR/MR 工作流或迁移 SSH 方案打下清晰基础。

• 后端
• 开发工具