在 Ubuntu 上配置 GitLab API 访问
一 准备与前置检查
- 确认 GitLab 实例可访问：确保 Ubuntu 能解析并连通你的 GitLab 地址（域名或 IP），必要时开放 80/443（HTTP/HTTPS）与 22（SSH）端口。若使用 UFW，可执行：sudo ufw allow http && sudo ufw allow https && sudo ufw allow OpenSSH。若通过 HTTPS 访问，建议配置有效证书（可使用 Let’s Encrypt 或手动证书）。如使用自签名证书，注意客户端需信任该证书，否则 API/HTTPS 调用会失败。
二 获取 GitLab API 访问令牌
- 登录 GitLab Web 界面，进入 User Settings → Access Tokens，为你的账户生成一个 Personal Access Token（勾选 api 权限，按需设置过期时间）。妥善保存生成的令牌字符串，后续在 Ubuntu 上调用 API 时作为身份凭证使用。
三 在 Ubuntu 上调用 GitLab API 的常用方式
- 使用 curl 直接请求（推荐将 $GITLAB_URL 与 $TOKEN 替换为实际值）
- 获取当前用户信息
curl --header "PRIVATE-TOKEN: $TOKEN" "$GITLAB_URL/api/v4/user"
- 列出项目（分页示例）
curl --header "PRIVATE-TOKEN: $TOKEN" "$GITLAB_URL/api/v4/projects?per_page=100&page=1"
- 创建项目（私有）
curl --request POST --header "PRIVATE-TOKEN: $TOKEN" \
--header "Content-Type: application/json" \
--data '{"name":"demo","visibility":"private"}' \
"$GITLAB_URL/api/v4/projects"
- 使用 Git 凭证存储避免交互式输入
# 将令牌写入 Git 的 HTTPS 凭证存储（会交互输入用户名，密码填生成的令牌）
git config --global credential.helper store
# 首次 git 操作（如 git ls-remote）按提示输入用户名与令牌，之后自动使用
git ls-remote https://$GITLAB_URL/namespace/project.git
- 使用 .netrc 文件（适合脚本/CI 非交互场景）
cat >> ~/.netrc <<EOF
machine $GITLAB_URL
login your_username
password $TOKEN
EOF
chmod 600 ~/.netrc
- 使用 Personal Access Token 进行 Git over HTTPS（等价方式）
git clone https://oauth2:$TOKEN@$GITLAB_URL/namespace/project.git
- 使用 GitLab Runner 或 CI 时，推荐将 $TOKEN 放入受保护的变量（如 CI/CD Variables），并在脚本中使用 PRIVATE-TOKEN 请求头或 GIT_ASKPASS 等方式安全注入，避免明文出现在日志中。
四 常见问题与排查
- 401 Unauthorized / 403 Forbidden：检查令牌是否有效、是否勾选 api 权限、是否过期；确认请求头使用了 PRIVATE-TOKEN 且值无多余空格或换行；若启用了 Two-Factor Authentication（2FA），必须使用 Personal Access Token 而非账户密码。
- SSL/TLS 证书错误：自签名证书需在客户端信任；或改用 HTTP（仅测试环境）；生产环境建议使用 Let’s Encrypt 或有效 CA 签发的证书，并确保证书链完整（服务器证书在前，随后是中间证书，最后是根证书）。
- 代理或公司网络限制：若 Ubuntu 位于代理后，需为 Git/ curl 正确配置 HTTP_PROXY/HTTPS_PROXY 环境变量；部分企业网关会拦截或重写请求，必要时联系网络管理员放行 $GITLAB_URL 域名与端口。
- API 版本与路径：GitLab API 默认前缀为 /api/v4；如使用较老版本，请确认 API 路径与特性兼容性。
- 速率限制：频繁调用可能触发限流，必要时在请求头中使用 RateLimit-Reset 信息做退避重试，或在 GitLab 管理端调整限流策略（企业版功能）。
