认证模型

本文档定义当前版本 GitCode CLI 的认证来源优先级和持久化语义。

当前模型

当前版本支持：

环境变量认证
本地配置持久化认证
单主机单活动用户模型
通用偏好配置持久化

当前版本不支持：

多账户切换的完整产品化体验
操作系统 keyring 集成

认证来源优先级

同一主机下，活动 token 的解析顺序为：

GC_TOKEN
GITCODE_TOKEN
本地配置文件中的已登录 token

也就是说：

只要设置了环境变量，环境变量始终覆盖本地存储
auth logout 只会清理本地存储，不会替你取消环境变量

持久化边界

auth login 成功后会将以下信息写入本地配置目录：

主机名
用户名
token
Git protocol

默认位置：

~/.config/gc/auth.json

可通过 GC_CONFIG_DIR 覆盖配置目录。

通用偏好配置写入同一配置目录下的：

~/.config/gc/config.json

当前通用配置用于保存 editor、browser、pager 等非敏感偏好。认证 token 仍只写入 auth.json。通用配置会拒绝 token、password、secret 等未列入允许列表的键。

主机传播语义

GC_HOST 或登录配置中的默认 host 会决定已接入共享 host-aware 认证入口的业务命令所使用的 GitCode 主机。
host 必须是受信的 hostname-only 值，例如 gitcode.com 或 enterprise.example.com；不能包含 URL scheme、路径、端口、用户名或空白字符。
业务 API 请求会把 GitCode Web 主机映射为对应 API 主机，例如 gitcode.com 映射到 api.gitcode.com，enterprise.example.com 映射到 api.enterprise.example.com。
默认 gitcode.com 下，环境变量 token 仍优先于本地 token。
非默认 host 下，业务命令只使用该 host 本地登录保存的 token，不会把通用 GC_TOKEN / GITCODE_TOKEN 转发到自定义 host。
如果需要使用非默认 host，请先使用 gc auth login --hostname <host> 为该 host 建立本地认证。
显式支持 --hostname 的 auth 子命令仍按该参数读取目标主机认证信息。

各命令统一语义

校验 token 有效性
成功后写入本地配置（主机名、用户名、token、Git protocol）
若同时存在环境变量，后续命令仍优先使用环境变量
未显式传 --with-token 时，需要交互式 TTY；非交互环境会直接报错
--web (-w): 打开浏览器引导用户从 GitCode Token 页面生成 token，再继续在终端中完成登录
--git-protocol (-p): 选择 Git 操作使用的协议，支持 https（默认）和 ssh

auth status

按统一优先级解析当前活动 token
显示 token 来源：GC_TOKEN、GITCODE_TOKEN 或 config
显式传 --hostname 时，按目标主机读取本地已存储 token，不再被通用环境变量覆盖
传 --show-token 时会输出完整 token，仅建议由人工在受控终端中临时使用，禁止作为脚本取 token 入口
--show-token 必须在交互式 TTY 中按提示输入 hostname 确认；非交互环境一律拒绝输出完整 token，没有 --yes 绕过

auth token

输出当前活动 token
与 auth status 看到的来源保持一致
显式传 --hostname 时，输出目标主机已存储 token，不再被通用环境变量覆盖
输出 token 前会向 stderr 输出安全警告；不要在日志、截图、脚本管道或 AI 代理上下文中暴露该输出
必须在交互式 TTY 中按提示输入 hostname 确认；非交互环境一律拒绝输出完整 token，没有 --yes 绕过

auth logout

清理本地配置中的认证信息
如果当前活动 token 来自环境变量，会明确提示用户手动 unset

代理配置

GitCode CLI 使用 Go 标准库 HTTP client，自动支持标准代理环境变量：

# HTTP 代理
export HTTP_PROXY="http://proxy.example.com:8080"

# HTTPS 代理
export HTTPS_PROXY="http://proxy.example.com:8080"

# 不走代理的地址（可选）
export NO_PROXY="localhost,127.0.0.1,.internal"

注意事项：

代理 URL 必须包含完整协议前缀（http:// 或 https://）
小写环境变量（http_proxy、https_proxy）也支持，但大写优先级更高
如果代理认证失败或 URL 格式错误，会报错：proxyconnect tcp: dial tcp: lookup ...

常见错误：

# 错误：缺少协议前缀
export HTTP_PROXY="proxy.example.com:8080"  # ✗

# 正确：包含完整 URL
export HTTP_PROXY="http://proxy.example.com:8080"  # ✓