GitHub Token 配置 - FailproofAI

GitHub 个人访问令牌（PAT）是解锁所有 AgentEye 资源的唯一凭证。使用一个令牌，您即可拉取 Docker 镜像、下载发布版二进制文件并安装 Python wheel 包，无需对各组件分别登录，也无需在团队内传递共享密钥。所有 AgentEye 资源均通过 agenteye-enterprise GitHub 组织分发；一旦您的组织获得访问权限，每位开发者或运维人员可自行生成并轮换各自的令牌，从而实现按人可审计、可撤销的访问控制。在每台机器上，将令牌设置为环境变量并配置 Docker 凭证：

export AGENTEYE_TOKEN=<your-github-pat>
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

用户名说明： GHCR 会忽略 docker login 中的用户名，完全依赖令牌进行认证，因此任意非空值均可使用。本文档使用 -u x 以保持简洁；在创建 Kubernetes 镜像拉取密钥的部署清单中，可使用更具描述性的用户名，例如 agenteye-enterprise。两种写法均可接受。

方案 A：经典令牌（推荐）

经典令牌是 AgentEye 最可靠的选择，因为 GHCR 的 docker login 和镜像拉取流程对经典令牌的支持最为全面且稳定。两个权限范围即可覆盖所有需求（拉取镜像和下载发布资源），一次认证即可完成，无需排查注册表的各种异常。其中 read:packages 是真正意义上的只读权限；而 repo 是唯一能够访问私有发布资源的经典权限范围，其定义本身较为宽泛——GitHub 将其定义为对私有仓库的完全控制权（读写权限）。

1. 创建令牌

前往 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)。

字段	值
Note	`agenteye-<机器名或团队名>`（例如 `agenteye-prod-server`）
Expiration	根据您的安全策略设置有效期；90 天是合理的默认值

标签说明： GitHub 对经典令牌将此字段标记为 Note，对细粒度令牌标记为 Token name。两者用途相同：作为便于后续审计和撤销的可读标识符。

2. 选择权限范围

权限范围	用途说明
`read:packages`	从 `ghcr.io/agenteye-enterprise/` 拉取 Docker 镜像及下载包资源
`repo`	读取 `agenteye-enterprise/releases` 中的私有仓库内容、原始文件及发布资源。这是 GitHub 宽泛的”完全控制私有仓库”范围（读写权限），并非只读范围——它只是唯一能授予私有发布资源访问权限的经典范围

无需其他权限范围。

3. 生成并复制令牌

点击 Generate token 并立即复制令牌值；该值仅显示一次。请将其存储至您的密钥管理器或环境变量中。

方案 B：细粒度令牌

细粒度令牌可将访问范围限定在特定仓库和权限上，是最严格的最小权限选项。当您的组织安全策略要求使用细粒度令牌时，请选择此方案。

注意： GHCR 对细粒度令牌的支持不如经典令牌稳定。如果按照以下步骤操作后 docker login 或 docker pull 失败，请回退至经典令牌（方案 A）。

1. 创建令牌

前往 GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token。

字段	值
Token name	`agenteye-<机器名或团队名>`（例如 `agenteye-prod-server`）
Expiration	根据您的安全策略设置有效期；90 天是合理的默认值
Resource owner	`agenteye-enterprise`
Repository access	Only select repositories → `agenteye-enterprise/releases`

2. 设置仓库权限

在 Permissions → Repository permissions 下，进行如下设置：

权限	访问级别
Contents	Read-only
Packages	Read-only

其他所有权限可保持 No access。

注意： 如果容器镜像（ghcr.io/agenteye-enterprise/...）作为组织级包而非仓库关联包发布，仅使用仓库范围的权限可能导致 Docker 登录失败。在这种情况下，请添加组织级权限：Permissions → Organization permissions → Packages: Read-only。

3. 各权限说明

权限	用途
Contents: Read-only	从 `agenteye-enterprise/releases` 下载 `docker-compose.yml`、发布版二进制文件及 Python wheel 包
Packages: Read-only	从 `ghcr.io/agenteye-enterprise/` 拉取 Docker 镜像

4. 生成并复制令牌

点击 Generate token 并立即复制令牌值；该值仅显示一次。请将其存储至您的密钥管理器或环境变量中。

轮换令牌

定期轮换令牌可保持访问的可审计性，并在凭证泄露时将影响范围降至最低。令牌也可能随时过期或被撤销，因此轮换是保持认证有效的常规方式。轮换步骤如下：

按照上述步骤生成新令牌。
在您的环境变量或密钥管理器中更新 AGENTEYE_TOKEN。
重新进行 Docker 认证：echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
在 GitHub → Settings → Developer settings → Personal access tokens 中撤销旧令牌，打开与令牌类型对应的 Tokens (classic) 或 Fine-grained tokens 子页面，将其删除。

验证令牌

在将令牌接入部署流程之前，请先确认其可正常使用，以便认证问题在此阶段暴露，而非在发布过程中出现。以下每条命令分别验证上述其中一个权限范围：

# Packages scope - authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

# Contents scope - fetch a raw release file
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o /tmp/agenteye-compose-check.yml

docker login 成功即表示包权限范围有效；文件下载成功即表示内容权限范围有效。

故障排查

现象	可能原因	解决方法
`docker login` 返回 401	令牌缺少 `Packages: Read-only`（细粒度）或 `read:packages`（经典）权限	添加包权限范围并重新生成令牌
`curl` 请求原始 GitHub URL 返回 404	令牌缺少 `Contents: Read-only` 或 `repo` 权限范围	添加内容权限范围并重新生成令牌
`gh release download` 返回 403	令牌未获授权访问 `agenteye-enterprise/releases`	确认该仓库已包含在细粒度令牌的仓库访问范围内，或改用带有 `repo` 范围的经典令牌
令牌被接受但找不到镜像	细粒度令牌缺少组织级包权限	添加组织级 `Packages: Read-only` 权限

如遇访问问题，请联系 support@exosphere.host。

​方案 A：经典令牌（推荐）

​1. 创建令牌

​2. 选择权限范围

​3. 生成并复制令牌

​方案 B：细粒度令牌

​1. 创建令牌

​2. 设置仓库权限

​3. 各权限说明

​4. 生成并复制令牌

​轮换令牌

​验证令牌

​故障排查

方案 A：经典令牌（推荐）

1. 创建令牌

2. 选择权限范围

3. 生成并复制令牌

方案 B：细粒度令牌

1. 创建令牌

2. 设置仓库权限

3. 各权限说明

4. 生成并复制令牌

轮换令牌

验证令牌

故障排查