DevContainer 开发环境¶

本文档统一说明 FastQTools 在 DevContainer 中的开发环境搭建，包括 VS Code 原生支持和 Windsurf/Cursor 的 SSH 连接方案。

适用范围¶

Windows 11/10 + Docker Desktop（WSL2 后端）
VS Code + Dev Containers 扩展
Windsurf / Cursor（通过 SSH 连接）

环境准备¶

1. 仓库必须在 WSL2 中打开¶

容器 bind mount 在 WSL2 Linux 文件系统下更稳定、性能更好：

# WSL2 中克隆仓库
mkdir -p ~/lessup
cd ~/lessup
git clone git@github.com:<org>/<repo>.git fastq-tools

VS Code 中通过 Remote - WSL 打开 ~/lessup/fastq-tools，再执行 Reopen in Container。

2. SSH Agent 配置¶

容器通过 SSH Agent 转发访问私有仓库（不将私钥复制进容器）：

# WSL 中启动 agent 并加载 key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 验证
ssh-add -l
ssh -T git@github.com

3. Git 身份配置¶

容器会从宿主机 WSL 自动挂载 ~/.gitconfig（只读）：

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

VS Code DevContainer¶

两种配置可选：

完整配置 (.devcontainer/devcontainer.json)：使用 docker-compose
简易配置 (.devcontainer/devcontainer.simple.json)：单 Dockerfile

两者均提供：Clang/LLVM 21、CMake、Ninja、Conan、VS Code C++ 扩展。

日常开发¶

# 容器内执行
./scripts/core/build
./scripts/core/test
./scripts/core/lint

Windsurf / Cursor SSH 方案¶

Windsurf/Cursor 不完全支持 "Reopen in Container"。解决方案是在 DevContainer 内启动 sshd，通过 SSH 直连。

实现方式¶

采用 DevContainer lifecycle hooks + sshd 自行 daemonize：

postCreateCommand：运行 setup-sshd.sh 一次性配置
postStartCommand：运行 start-sshd.sh 每次启动拉起 sshd

sshd 配置：端口 2222、禁用密码登录、禁用 root 登录、限制用户 developer。

连接步骤¶

本机开发¶

用 VS Code Dev Containers 启动容器（或 devcontainer CLI）
确认 postStartCommand 已执行（sshd 自动启动）
测试连接：

ssh -p 2222 developer@127.0.0.1

在 Windsurf/Cursor 中使用 Remote-SSH：
Host: 127.0.0.1
Port: 2222
User: developer
工作目录: /workspace

远程主机¶

在远程主机上启动 DevContainer
设置 FASTQTOOLS_SSH_BIND=0.0.0.0（注意防火墙）
本地 Windsurf/Cursor 直连 remote-host:2222

端口配置¶

通过环境变量自定义：

FASTQTOOLS_SSH_BIND（默认 127.0.0.1）
FASTQTOOLS_SSH_PORT（默认 2222）

快速命令参考¶

# 手动启动容器
docker start fastqtools-dev

# 手动启动 sshd
docker exec fastqtools-dev bash /workspace/.devcontainer/scripts/start-sshd.sh

# SSH 连接
ssh -p 2222 developer@localhost

常见问题¶

SSH Agent 未检测到¶

# WSL 中执行
eval "$(ssh-agent -s)" && ssh-add

# 然后在 VS Code 中 Rebuild and Reopen in Container

Git Permission denied (publickey)¶

ssh-add -l          # 确认 key 已加载
ssh -T git@github.com  # 测试连接

SSH Connection refused¶

容器未启动或 postStartCommand 未执行
检查端口映射：docker port fastqtools-dev

SSH Permission denied (publickey)¶

检查容器内 /home/developer/.ssh_authorized_keys 是否存在且权限为 0600

性能很慢¶

确认仓库位于 WSL2 Linux 文件系统（不是 Windows 盘符下）
缓存使用命名卷或用户目录

安全建议¶

sshd 默认只绑定 127.0.0.1
对外开放时配合防火墙
已禁用密码登录，仅公钥认证