Self Hosted Instances

自建 GitLab、Gitea 与 GitHub Enterprise

TriForge 接收的是实例首页 URL，不是 REST API URL。它会根据平台自动拼接 API 路径。

正确 URL 示例

场景	应输入
自建 GitLab 根路径	https://gitlab.example.com
自建 GitLab 带前缀	https://code.example.com/gitlab
自建 Gitea 根路径	https://git.example.com
自建 Gitea 带前缀	https://code.example.com/gitea
GitHub Enterprise Server	https://github.example.com

不要输入：

https://gitlab.example.com/api/v4
https://git.example.com/api/v1
https://github.example.com/api/v3

TriForge 会自动得到：

• GitLab：<首页路径>/api/v4；
• Gitea：<首页路径>/api/v1；
• GitHub Enterprise：<首页路径>/api/v3。

URL 不能包含用户名、密码、查询参数或 fragment。

路径前缀的重要性

若实例部署在 /gitea，必须保留此前缀：

https://code.example.com/gitea

它不仅用于 API 地址，也用于限制 Token 只发送给匹配的 Git HTTPS remote。输入成 https://code.example.com 可能导致 API 404，或使 remote 与连接无法安全匹配。

反向代理要求

代理应正确处理：

• HTTPS 终止与完整证书链；
• 原始 Host 与路径前缀；
• Git 的 smart HTTP 路径；
• GitLab /api/v4 或 Gitea /api/v1；
• 合理的请求/响应大小与超时；
• 不把认证端点重定向到另一主机。

TriForge 的带 Token API 请求不跟随重定向，这是为了防止 Authorization 信息被带到错误服务器。若实例把所有 API 请求从旧域名 301/302 到新域名，请直接把最终 HTTPS 首页 URL 配进 TriForge。

HTTPS 与企业 CA

使用公开受信任证书时通常无需额外设置。公司 CA 或自签名证书可能出现一种常见情况：

• 浏览器能打开；
• 系统 Git 能 Push；
• 但 VS Code 扩展宿主的 Node HTTPS 请求不信任该 CA；

或者反过来。原因是 Git 和扩展宿主可能使用不同的证书信任来源。

推荐：

1. 让管理员为实例部署完整、有效的证书链；
2. 按组织标准把根 CA 安装到系统/VS Code 扩展宿主可用的信任链；
3. 重启 VS Code 后重新验证；
4. 同时用浏览器、git ls-remote 和 TriForge 分别检查。

不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，也不要全局关闭 http.sslVerify。这会把所有 HTTPS 连接暴露给中间人攻击。

0.5.0 没有自定义 CA 文件设置；若组织环境需要这一功能，请提交功能请求并说明平台、证书链和 VS Code 运行环境。

HTTP 实例

TriForge 允许用户明确确认后连接 http://，但不推荐。HTTP 中 Token 和 Git 内容没有传输加密，局域网也不能自动视为可信。

只应在以下情况短暂使用：

• 完全隔离的本机开发容器；
• 无真实 Token、无真实代码的测试实例；
• 确认网络边界且理解风险。

代理与 VPN

出现超时或连接重置时检查：

• VS Code 所在进程是否经过企业代理；
• Remote SSH/Dev Container 中的扩展宿主是否能访问实例；
• VPN 是否只给浏览器路由、未覆盖扩展宿主；
• 代理是否拒绝长时间 Git Push；
• 防火墙是否允许 API 和 Git HTTPS 两类路径。

TriForge 的 API 与 git 子进程是两套网络客户端，“API 能连接”不保证“Git Push 能通过”，反之亦然。

版本与管理员策略

自建平台可能：

• 禁用个人访问令牌；
• 限制 Token 最大有效期；
• 禁止普通用户创建项目；
• 要求组织 SSO；
• 强制分支保护或签名提交；
• 更改仓库名规则；
• 对 API 加入额外身份代理。

TriForge 不能绕过这些服务端政策。验证连接只验证身份；创建和 Push 仍可能被后续策略拒绝。

更换域名或迁移实例

不要直接把 Git remote 改到新主机后继续沿用旧连接。安全顺序是：

1. 在新实例创建专用 Token；
2. 修改 TriForge 连接的实例 URL；
3. 第 3 步输入新 Token 并验证；
4. 检查或更新项目 Git remote；
5. Fetch，查看提交图中的远程位置；
6. 先用测试分支推送；
7. 确认迁移完成后撤销旧实例 Token。

由于 URL 改变时 TriForge 强制要求新 Token，旧凭据不会被发送给新主机。

基础诊断

在不暴露 Token 的前提下收集：

git --version
git remote -v
git ls-remote https://gitlab.example.com/user/project.git

同时查看 VS Code“输出” → “TriForge Git”。复制日志前仍应人工检查内部域名、用户名、仓库名是否适合公开。

参见 安全设计 与 故障排查。