适用场景
当你把编码智能体(自动修 Bug、跑测试、开 PR 的那类工具)跑在容器或沙箱里,需要让它访问 Git 仓库、包管理器和 CI,但不想把长期 Personal Access AI 词典:Token">Token 明文塞进环境变量或 ~/.git-credentials 时,这套方案适用。核心思路是三件事:令牌由凭证代理按需签发、有效期以分钟计;权限按仓库和操作类型收窄到刚好够用;所有出网流量走白名单代理并留审计日志。这样即使智能体被提示注入或代码里藏了外传逻辑,能拿到的也只是一份很快过期、只能碰指定仓库的凭证。
环境与前置条件
- 一台可运行容器的 Linux 主机或编排平台(Kubernetes 或普通 Docker 均可)。若在 Kubernetes 上,可使用投影 ServiceAccount 令牌做工作负载身份;若不在,可替换为 mTLS 客户端证书或云厂商工作负载身份,校验思路一致。
- 凭证代理运行环境:Python 3.10 以上(以官方文档当前版本为准),依赖
fastapi、uvicorn、httpx、pyjwt[crypto]、pyyaml。 - 一个 GitHub App(组织级),用于签发安装令牌。私钥文件放在代理所在主机,权限 600,绝不进入智能体容器。
- 一台出网正向代理(Squid 或 Envoy 均可),智能体容器只能访问它,不能直连公网。
- 资源建议:凭证代理 1 核 512MB 内存足够;代理与日志采集各 1 核 1GB;智能体容器按任务规模给,磁盘留 10GB 以上用于克隆仓库和装依赖。不需要 GPU。
分步骤部署
第一步:创建 GitHub App 并做仓库级授权
在组织设置里新建 GitHub App,把仓库选择设为「Only select repositories」,只勾选允许智能体改动的仓库。权限按最小集配置:Contents 读写、Pull requests 读写、Metadata 只读,其余全部设为 No access。生成私钥后下载到代理主机:
```bash
install -m 600 /path/to/downloaded.pem /etc/token-broker/app.pem
```
把 App ID 和 Installation ID 记录下来,后续通过环境变量注入代理。注意安装令牌的有效期由 GitHub 决定(通常一小时),不需要也不能自行延长;App 的 JWT 有效期上限是 10 分钟,这是官方固定规则。
第二步:编写凭证代理的策略文件
策略文件描述「哪个工作负载可以拿哪个仓库的什么权限」:
```yaml
/etc/token-broker/policy.yaml
coding-agent-bugfix:
repositories:
- example-org/example-service
permissions:
contents: write
pull_requests: write
metadata: read
ttl_seconds: 900
max_requests_per_hour: 20
```
repositories 的取值必须落在 App 已授权的仓库范围内,permissions 必须是 App 已授予权限的子集,否则 GitHub 会直接拒绝。这一层是二次收窄:App 层面放宽到多个仓库,代理层面再按任务收到单个仓库。
第三步:部署凭证代理服务
代理只做四件事:校验调用方身份、查策略、向 GitHub 换令牌、写审计日志。
```python
/opt/token-broker/app.py
import json, os, time, logging
import httpx, jwt
from fastapi import FastAPI, Header, HTTPException, Request
APP_ID = os.environ["GH_APP_ID"]
INSTALLATION_ID = os.environ["GH_INSTALLATION_ID"]
PRIVATE_KEY = open(os.environ["GH_APP_PRIVATE_KEY_PATH"]).read()
K8S_API = os.environ.get("K8S_API", "https://kubernetes.default.svc")
K8S_TOKEN = open("/var/run/secrets/kubernetes.io/serviceaccount/token").read()
K8S_CA = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
app = FastAPI()
logging.basicConfig(level=logging.INFO)
log = logging.getLogger("token-broker")
def audit(event: dict) -> None:
event["ts"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
print(json.dumps(event, ensure_ascii=False), flush=True)
async def verify_workload(token: str) -> str:
"""用 Kubernetes TokenReview 校验调用方身份,返回 ServiceAccount 名。"""
async with httpx.AsyncClient(verify=K8S_CA, timeout=5) as c:
r = await c.post(
f"{K8S_API}/apis/authentication.k8s.io/v1/tokenreviews",
headers={"Authorization": f"Bearer {K8S_TOKEN}"},
json={
"apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview",
"spec": {"token": token, "audiences": ["token-broker"]},
},
)
body = r.json()
if not body.get("status", {}).get("authenticated"):
raise HTTPException(status_code=401, detail="workload identity rejected")
return body["status"]["user"]["username"].split(":")[-1]
def app_jwt() -> str:
now = int(time.time())
iat 回拨 60 秒容忍时钟漂移,总时长不超过 10 分钟
return jwt.encode({"iat": now - 60, "exp": now + 480, "iss": APP_ID},
PRIVATE_KEY, algorithm="RS256")
async def mint(repos: list[str], perms: dict) -> dict:
async with httpx.AsyncClient(timeout=10) as c:
r = await c.post(
f"https://api.github.com/app/installations/{INSTALLATION_ID}/access_tokens",
headers={
"Authorization": f"Bearer {app_jwt()}",
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
},
json={"repositories": repos, "permissions": perms},
)
r.raise_for_status()
return r.json()
@app.post("/v1/token")
async def issue(request: Request, authorization: str = Header(...)):
workload_token = authorization.removeprefix("Bearer ").strip()
workload = await verify_workload(workload_token)
import yaml
policy = yaml.safe_load(open(os.environ["POLICY_PATH"]))
spec = policy.get(workload)
if not spec:
audit({"event": "deny", "workload": workload, "reason": "no_policy"})
raise HTTPException(status_code=403, detail="no policy for workload")
data = await request.json()
repo = data.get("repo")
if repo not in spec["repositories"]:
audit({"event": "deny", "workload": workload, "repo": repo,
"reason": "repo_not_allowed"})
raise HTTPException(status_code=403, detail="repo not allowed")
result = await mint([repo.split("/")[1]], spec["permissions"])
token = result["token"]
audit({
"event": "issue",
"workload": workload,
"repo": repo,
"permissions": spec["permissions"],
"expires_at": result.get("expires_at"),
"token_fp": __import__("hashlib").sha256(token.encode()).hexdigest()[:12],
})
return {"token": token, "expires_at": result.get("expires_at")}
```
启动命令:
```bash
cd /opt/token-broker && \
GH_APP_ID=... GH_INSTALLATION_ID=... \
GH_APP_PRIVATE_KEY_PATH=/etc/token-broker/app.pem \
POLICY_PATH=/etc/token-broker/policy.yaml \
uvicorn app:app --host 0.0.0.0 --port 8080
```
看到 Uvicorn running on http://0.0.0.0:8080 即启动成功。日志里绝不打印令牌明文,只记录 SHA256 前 12 位指纹,用于事后比对。
第四步:配置出网白名单代理
智能体容器不直连公网,默认路由指向代理;代理只放行必要域名:
```conf
squid.conf 片段
acl allowed_domains dstdomain .github.com .githubusercontent.com .pypi.org .npmjs.org
acl metadata_ip dst 169.254.169.254
http_access deny metadata_ip
http_access allow allowed_domains
http_access deny all
access_log /var/log/squid/access.log
```
dstdomain 前加点表示匹配该域名及其子域。metadata_ip 那条很关键:云主机元数据接口常被用来偷长期凭证,必须封死。修改后执行 squid -k reconfigure 生效。
第五步:在智能体容器内注入令牌
容器启动脚本先换取令牌,只在进程环境里保存,不写文件:
```bash
#!/usr/bin/env bash
/usr/local/bin/get-token.sh
set -euo pipefail
: "${BROKER_URL:?BROKER_URL 未设置}"
WORKLOAD_TOKEN=$(cat /var/run/secrets/token-broker/token)
curl -sS -f -X POST "${BROKER_URL}/v1/token" \
-H "Authorization: Bearer ${WORKLOAD_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"repo\":\"${TARGET_REPO}\"}" | jq -r .token
```
再配一个不落盘的 git 凭证助手:
```bash
#!/usr/bin/env bash
/usr/local/bin/git-credential-env
case "${1:-}" in
get)
echo "username=x-access-token"
echo "password=${GH_TOKEN}"
;;
esac
```
入口脚本里串起来:
```bash
export GH_TOKEN="$(/usr/local/bin/get-token.sh)"
git config --global credential.helper /usr/local/bin/git-credential-env
git config --global credential.useHttpPath true
```
x-access-token 是 GitHub App 安装令牌约定的用户名,配合令牌作为密码使用。
第六步:跑一次修 Bug 并提 PR 的任务
```bash
git clone "https://github.com/${TARGET_REPO}.git" /workspace/repo
cd /workspace/repo
git checkout -b "fix/agent-$(date +%s)"
此处交给智能体修改代码
git -c user.name="coding-agent" -c user.email="agent@example.invalid" \
commit -am "fix: 修正边界条件下的空指针"
git push -u origin HEAD
```
PR 通过 API 创建,同样复用环境里的短期令牌,不需要另配凭证:
```bash
curl -sS -f -X POST \
-H "Authorization: Bearer ${GH_TOKEN}" \
-H "Accept: application/vnd.github+json" \
"https://api.github.com/repos/${TARGET_REPO}/pulls" \
-d "{\"title\":\"fix: 修正边界条件下的空指针\",\"head\":\"$(git branch --show-current)\",\"base\":\"main\"}"
```
任务结束后销毁容器,令牌随环境一起消失,无需回收动作。
验证部署是否成功
1. 白名单外域名应被拒绝:
```bash
curl -sS -o /dev/null -w "%{http_code}\n" --proxy http://egress-proxy:3128 https://pypi.org
curl -sS -o /dev/null -w "%{http_code}\n" --proxy http://egress-proxy:3128 https://example.com
```
预期第一条返回 200,第二条返回 403 或连接被拒。
2. 元数据接口应不可达:
```bash
curl -sS -m 5 http://169.254.169.254/ ; echo "exit=$?"
```
预期超时或连接拒绝,不会返回任何实例信息。
3. 容器内不应存在明文凭证文件:
```bash
ls -la ~/.git-credentials 2>&1
env | grep -i -E 'token|secret' | sed 's/=.*/=<redacted>/'
```
预期第一条报文件不存在;第二条只看到短期的 GH_TOKEN 和代理地址,没有长期密钥。
4. 代理侧审计日志应出现签发记录:
```bash
docker logs token-broker 2>&1 | grep '"event": "issue"' | tail -n 3
```
预期能看到 workload、repo、expires_at 和 token_fp 字段,且没有完整令牌字符串。
5. 令牌确实会过期:
```bash
sleep 1000 && git push # 超过策略里的 ttl_seconds 后重试
```
预期返回 401,说明短时效生效,而不是永久有效。
6. PR 创建结果:curl 返回体中 html_url 字段有值,浏览器打开能看到由智能体分支发起的 PR,且改动范围只落在目标仓库。
常见报错与解决
报错:remote: Permission to example-org/example-service.git denied to x-access-token
→ 原因:GitHub App 未安装到该仓库,或代理申请时请求的权限超出 App 已授予范围。
→ 解决:检查 App 的仓库选择列表,确认目标仓库已勾选;再核对策略文件里的 permissions 是否为 App 权限的子集。可用以下命令确认安装范围:
```bash
curl -sS -H "Authorization: Bearer ${GH_TOKEN}" \
https://api.github.com/repos/example-org/example-service | jq '.permissions'
```
报错:fatal: could not read Username for 'https://github.com': No such device or address
→ 原因:credential helper 未生效,或 GH_TOKEN 在该 shell 里为空(常见于 export 写在子 shell 中)。
→ 解决:确认 helper 已注册并在当前 shell 可见:
```bash
git config --global --get credential.helper
echo "${GH_TOKEN:+token-present}"
```
若第二行没有输出,说明令牌没注入到当前进程,改由入口脚本统一 export 后再启动子进程。
报错:403 Forbidden 或 Proxy CONNECT aborted(访问包管理器时)
→ 原因:目标域名不在 Squid 白名单,或被 http_access deny all 兜底拦截。
→ 解决:把域名加入 allowed_domains 后重新加载:
```bash
squid -k reconfigure && tail -n 20 /var/log/squid/access.log
```
报错:凭证代理返回 401 workload identity rejected
→ 原因:投影令牌的 audience 与 TokenReview 请求中的 audiences 不一致,或令牌已超过 expirationSeconds。
→ 解决:核对 Pod 卷配置里的 audience: token-broker,并确认 expirationSeconds 大于任务时长;重启 Pod 让令牌重新投影。
报错:A JSON web token could not be decoded 或 'iss' claim is invalid
→ 原因:App JWT 的 iss 不是 App ID 字符串,或 exp 超过 10 分钟上限,或主机时钟偏移过大。
→ 解决:确认 iss 使用 App ID 而非 Client ID;把 JWT 有效期压到 9 分钟以内并保留 60 秒回拨;对宿主机开启时间同步。
报错:Resource not accessible by integration
→ 原因:App 权限不足,或安装令牌被收窄到不含该操作的权限集。
→ 解决:在 App 设置里补上对应权限并重新安装,同时更新策略文件中的 permissions。
后续维护
凭证轮换:GitHub App 私钥建议按季度轮换。做法是先在 App 页面生成新私钥,把新文件放到代理主机并更新 GH_APP_PRIVATE_KEY_PATH 指向,重启代理验证签发正常后,再删除旧私钥。整个过程不需要改动智能体侧任何代码。
策略演进:随着智能体任务类型增加,策略文件会变长。建议把「仓库 → 允许的权限 → 每小时请求上限」做成评审项,新增条目走代码评审而非线上手改,避免权限悄悄放大。
日志留存与关联:凭证代理日志记录「谁在什么时候拿了哪个仓库的令牌」,出网代理日志记录「这个工作负载访问了哪些域名」。两边都带 workload 标识,按时间窗口关联即可还原一次任务的完整行为。留存周期按合规要求设定,日志本身不含令牌明文,可以放心长期保存。
监控告警:对三类信号设阈值告警——单工作负载每小时令牌申请次数突增、出现 deny 事件(说明有越权尝试或策略漏配)、出网代理出现大量非白名单拒绝。前两类通常意味着智能体被注入或任务配置错误,值得立即人工介入。
升级:代理依赖的框架与 GitHub API 版本会更新,升级前先看官方文档的变更说明,尤其是 API 版本头(示例中的 X-GitHub-Api-Version)与权限名称的变化;具体版本号以官方文档当前版本为准。升级顺序建议先在预发环境跑一遍完整的「修 Bug → 提 PR」流程,再切生产。
