f407de1844
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>
210 lines
5.3 KiB
Markdown
210 lines
5.3 KiB
Markdown
# 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、日志
|
||
|
||
当前结构：
|
||
|
||
```text
|
||
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` 仓库：
|
||
|
||
```bash
|
||
GIT_CRED_PROXY_PROTOCOLS=https,http ./host/start.sh
|
||
```
|
||
|
||
## 使用
|
||
|
||
### 1. 宿主机启动代理
|
||
|
||
在宿主机进入这个项目目录：
|
||
|
||
```bash
|
||
./host/start.sh
|
||
```
|
||
|
||
查看状态：
|
||
|
||
```bash
|
||
./host/status.sh
|
||
```
|
||
|
||
### 2. 确保容器能访问这个项目目录
|
||
|
||
容器里的 Git helper 会直接引用这个项目目录下的脚本和 `host/state/token`。
|
||
|
||
所以你需要保证这个目录也能在容器里看到，例如：
|
||
|
||
- 宿主机和容器都共享 `/workspaces`
|
||
- 或者把这个目录单独挂载到容器内
|
||
|
||
### 3. 容器里配置 Git helper
|
||
|
||
如果你当前就在挂载后的 `host-git-cred-proxy` 项目根目录，直接执行：
|
||
|
||
```bash
|
||
./container/configure-git.sh
|
||
```
|
||
|
||
如果你想只作用于当前仓库：
|
||
|
||
```bash
|
||
cd /path/to/your/repo
|
||
/path/to/host-git-cred-proxy/container/configure-git.sh --local
|
||
```
|
||
|
||
或者显式指定仓库：
|
||
|
||
```bash
|
||
/path/to/host-git-cred-proxy/container/configure-git.sh --local --repo /path/to/your-repo
|
||
```
|
||
|
||
如果这个项目在容器里不是当前目录，而是挂载在固定位置，例如 `/opt/host-git-cred-proxy`，那就执行：
|
||
|
||
```bash
|
||
/opt/host-git-cred-proxy/container/configure-git.sh
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
```bash
|
||
git ls-remote origin
|
||
```
|
||
|
||
或者：
|
||
|
||
```bash
|
||
printf 'protocol=https\nhost=example.com\npath=owner/repo.git\n\n' | git credential fill
|
||
```
|
||
|
||
## 接入示例
|
||
|
||
这两个示例都假设你已经在宿主机启动了代理：
|
||
|
||
```bash
|
||
./host/start.sh
|
||
```
|
||
|
||
### docker-compose
|
||
|
||
示例文件：`examples/docker-compose.yml`
|
||
|
||
使用前先设置宿主机项目路径：
|
||
|
||
```bash
|
||
export HOST_GIT_CRED_PROXY_DIR=/workspaces/host-git-cred-proxy
|
||
```
|
||
|
||
然后把示例复制到你的项目里：
|
||
|
||
```bash
|
||
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` 改成：
|
||
|
||
```bash
|
||
http://localhost:18765
|
||
```
|
||
|
||
### devcontainer
|
||
|
||
示例文件：`examples/devcontainer.json`
|
||
|
||
先在宿主机设置：
|
||
|
||
```bash
|
||
export HOST_GIT_CRED_PROXY_DIR=/workspaces/host-git-cred-proxy
|
||
```
|
||
|
||
然后复制到你的项目：
|
||
|
||
```bash
|
||
mkdir -p .devcontainer
|
||
cp /workspaces/host-git-cred-proxy/examples/devcontainer.json .devcontainer/devcontainer.json
|
||
```
|
||
|
||
这个示例会：
|
||
|
||
- 把当前工作区挂到容器内的 `/workspace`
|
||
- 额外挂载 `host-git-cred-proxy` 到 `/opt/host-git-cred-proxy`
|
||
- 在容器创建完成后自动执行 `/opt/host-git-cred-proxy/container/configure-git.sh --global`
|
||
|
||
如果你的本地路径不是 `/workspaces/host-git-cred-proxy`，只要把 `HOST_GIT_CRED_PROXY_DIR` 换成真实绝对路径即可。
|
||
|
||
## 可选环境变量
|
||
|
||
- `GIT_CRED_PROXY_HOST`：宿主机监听地址，默认 `127.0.0.1`
|
||
- `GIT_CRED_PROXY_PORT`：宿主机监听端口，默认 `18765`
|
||
- `GIT_CRED_PROXY_PUBLIC_URL`：容器访问地址，默认 `http://host.docker.internal:<port>`
|
||
- `GIT_CRED_PROXY_PROTOCOLS`：允许代理的协议列表，默认 `https`
|
||
- `GIT_CRED_PROXY_ALLOWED_HOSTS`：可选，限制允许代理的 host，逗号分隔
|
||
- `GIT_CRED_PROXY_URL`：容器 helper 访问代理的地址，默认 `http://host.docker.internal:18765`
|
||
- `GIT_CRED_PROXY_TOKEN`：可选，直接传 token，优先于 token 文件
|
||
- `GIT_CRED_PROXY_TOKEN_FILE`：可选，自定义 token 文件路径
|
||
- `GIT_CRED_PROXY_RUNTIME`：可选，显式指定 `bun` 或 `node`
|
||
|
||
## 安全说明
|
||
|
||
- 服务端默认只监听 `127.0.0.1`
|
||
- token 存在 `host/state/` 下，并通过 `.gitignore` 忽略
|
||
- 只要容器能读取这个目录，也就能读取 token
|
||
- 这适合你信任当前容器的开发场景，不适合不可信容器或多租户环境
|
||
|
||
## 停止代理
|
||
|
||
```bash
|
||
./host/stop.sh
|
||
```
|