ddev-ssh-agent Docker 镜像文档

1. 镜像概述

ddev-ssh-agent 是 DDEV 工具链的一部分，基于 nardeas/docker-ssh-agent（commit: fb6822d0003d1c0a795e183f5d257c2540fa74a4）构建。该镜像提供 Docker 网络环境内的 SSH 代理服务，主要用于 DDEV 本地开发环境的 SSH 密钥管理与认证，通常不建议独立使用。

2. 核心功能与特性

• Docker 网络内 SSH 代理：在 Docker 网络中提供 ssh-agent 服务，统一管理 SSH 密钥。
• 密钥安全管理：支持添加、删除 SSH 密钥，避免密钥在多个容器中重复存储。
• 跨容器共享：通过卷挂载实现 SSH 认证套接字在多个容器间共享，简化 SSH 认证流程。

3. 使用场景与适用范围

• DDEV 本地开发环境：作为 DDEV 工具链的组件，用于处理需要 SSH 认证的场景（如克隆私有代码仓库、SSH 隧道连接等）。
• 多容器协作：在需要跨容器共享 SSH 认证状态的 Docker 工作流中，提供统一的密钥代理服务。

4. 使用方法

4.1 推荐使用方式（通过 DDEV）

ddev-ssh-agent 是 DDEV 的内置组件，通过 DDEV 工具自动管理，无需手动配置。DDEV 会在启动项目时自动创建并管理 ssh-agent 容器，包括密钥添加、套接字共享等流程。

详细使用方法请参考 DDEV 官方文档。

4.2 独立使用（不推荐，仅作参考）

该镜像设计为 DDEV 的一部分，独立使用需手动配置，仅建议用于了解内部机制。

4.2.1 启动 ssh-agent 容器

docker run -d --name=ssh-agent ddev/ddev-ssh-agent

4.2.2 添加 SSH 密钥

通过临时容器将本地 SSH 密钥添加到 ssh-agent：

docker run --rm --volumes-from=ssh-agent -v ~/.ssh:/.ssh -it ddev/ddev-ssh-agent ssh-add /root/.ssh/id_rsa

说明：~/.ssh 为本地密钥目录，id_rsa 为目标密钥文件名，根据实际情况替换。

4.2.3 在其他容器中使用

通过卷挂载和环境变量共享 ssh-agent 套接字：

方法 1：使用 docker run

docker run -it --volumes-from=ssh-agent -e SSH_AUTH_SOCK=/.ssh-agent/socket ubuntu:latest /bin/bash

方法 2：使用 docker-compose

在 docker-compose.yml 中添加配置：

services:
  your-service:
    volumes_from:
      - ssh-agent
    environment:
      - SSH_AUTH_SOCK=/.ssh-agent/socket

5. 配置说明

5.1 核心配置参数

5.2 非 root 用户配置

若容器内使用非 root 用户，需通过 socat 代理套接字并调整权限：

# 1. 安装 socat
apt-get update && apt-get install -y socat

# 2. 创建代理套接字
socat UNIX-LISTEN:~/.ssh/socket,fork UNIX-CONNECT:/.ssh-agent/socket &

# 3. 调整权限
chown $(id -u) ~/.ssh/socket

# 4. 设置环境变量
export SSH_AUTH_SOCK=~/.ssh/socket

6. 支持与反馈

6.1 获取帮助

• DDEV 社区 ***
• Stack Overflow（ddev 标签）

6.2 问题反馈

• 提交 Issue：GitHub Issues
• 文档参考：DDEV 官方文档、DDEV 官网

7. 关于 DDEV

DDEV 是一款开源工具，用于快速搭建本地 Web 开发环境，支持 PHP 和 Node.js。通过 Docker 实现标准化环境，无需 Docker 经验即可使用，支持环境扩展、版本控制和共享，简化开发流程。

8. 许可证信息

• 镜像包含软件的许可证信息：DDEV 许可证
• 镜像可能包含其他软件（如 Bash、基础系统组件等），其许可证需参考各自的分发协议。使用前请确保符合所有包含软件的许可证要求。