Files

严浩 f407de1844 Update container path documentation

Align the docs with the reorganized project layout so container setup commands match the paths users actually run.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-03-08 18:35:38 +08:00

5.3 KiB

Raw Permalink Blame History

host-git-cred-proxy

让 Docker 容器复用宿主机现有的 Git HTTPS 凭证。

适用场景：

macOS + OrbStack / Docker Desktop
容器里使用 https://... Git remote
宿主机已经能通过自己的 git credential 正常取到凭证

工作方式：

宿主机启动一个只监听 127.0.0.1 的代理服务
代理服务内部调用宿主机自己的 git credential fill/approve/reject
容器里的 Git helper 把 Git 的凭证请求转发到宿主机代理

这意味着它代理的是“宿主机 Git 当前能取到的 HTTPS 凭证”，不是 macOS 全部系统密码。

目录结构

host/：只在宿主机运行
container/：只在容器里运行
examples/：接入示例
host/state/：运行时状态目录，存 token、pid、日志

当前结构：

host-git-cred-proxy/
├── host/
│   ├── server.mjs
│   ├── start.sh
│   ├── status.sh
│   ├── stop.sh
│   └── state/
├── container/
│   ├── configure-git.sh
│   ├── git-credential-hostproxy
│   └── helper.mjs
├── examples/
│   ├── devcontainer.json
│   └── docker-compose.yml
├── package.json
└── README.md

默认行为

默认代理所有 https Git 凭证
默认监听 127.0.0.1:18765
容器默认通过 http://host.docker.internal:18765 访问宿主机
token 生成到 ./host/state/token

如果你还要代理 http 仓库：

GIT_CRED_PROXY_PROTOCOLS=https,http ./host/start.sh

使用

1. 宿主机启动代理

在宿主机进入这个项目目录：

./host/start.sh

查看状态：

./host/status.sh

2. 确保容器能访问这个项目目录

容器里的 Git helper 会直接引用这个项目目录下的脚本和 host/state/token。

所以你需要保证这个目录也能在容器里看到，例如：

宿主机和容器都共享 /workspaces
或者把这个目录单独挂载到容器内

3. 容器里配置 Git helper

如果你当前就在挂载后的 host-git-cred-proxy 项目根目录，直接执行：

./container/configure-git.sh

如果你想只作用于当前仓库：

cd /path/to/your/repo
/path/to/host-git-cred-proxy/container/configure-git.sh --local

或者显式指定仓库：

/path/to/host-git-cred-proxy/container/configure-git.sh --local --repo /path/to/your-repo

如果这个项目在容器里不是当前目录，而是挂载在固定位置，例如 /opt/host-git-cred-proxy，那就执行：

/opt/host-git-cred-proxy/container/configure-git.sh

4. 验证

git ls-remote origin

或者：

printf 'protocol=https\nhost=example.com\npath=owner/repo.git\n\n' | git credential fill

接入示例

这两个示例都假设你已经在宿主机启动了代理：

./host/start.sh

docker-compose

示例文件：examples/docker-compose.yml

使用前先设置宿主机项目路径：

export HOST_GIT_CRED_PROXY_DIR=/workspaces/host-git-cred-proxy

然后把示例复制到你的项目里：

cp /workspaces/host-git-cred-proxy/examples/docker-compose.yml ./docker-compose.yml
docker compose up -d

这个示例会：

把当前项目挂到容器内的 /workspace
把 host-git-cred-proxy 挂到容器内的 /opt/host-git-cred-proxy
容器启动时自动执行 /opt/host-git-cred-proxy/container/configure-git.sh --global

如果你在 OrbStack 里用 network_mode: host，也可以把 GIT_CRED_PROXY_URL 改成：

http://localhost:18765

devcontainer

示例文件：examples/devcontainer.json

先在宿主机设置：

export HOST_GIT_CRED_PROXY_DIR=/workspaces/host-git-cred-proxy

然后复制到你的项目：

mkdir -p .devcontainer
cp /workspaces/host-git-cred-proxy/examples/devcontainer.json .devcontainer/devcontainer.json