-
Notifications
You must be signed in to change notification settings - Fork 0
DevContainer and Docker
shijiashuai edited this page Mar 9, 2026
·
1 revision
本页面涵盖 FastQTools 的容器化开发环境搭建和生产部署方案。
- Windows 11/10 + Docker Desktop(WSL2 后端)
- VS Code + Dev Containers 扩展
- Windsurf / Cursor(通过 SSH 连接)
容器 bind mount 在 WSL2 Linux 文件系统下更稳定、性能更好:
mkdir -p ~/lessup && cd ~/lessup git clone git@github.com:LessUp/fastq-tools.git
VS Code 通过 Remote - WSL 打开项目,再执行 Reopen in Container。
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519 ssh -T git@github.com # 验证
容器自动挂载 ~/.gitconfig(只读)。
两种可选:
| 配置 | 文件 | 说明 |
|---|---|---|
| 完整配置 | devcontainer.json |
docker-compose 模式 |
| 简易配置 | devcontainer.simple.json |
单 Dockerfile |
两者均提供:Clang/LLVM 21、CMake、Ninja、Conan、VS Code C++ 扩展。
./scripts/core/build # 构建 ./scripts/core/test # 测试 ./scripts/core/lint # 代码质量
Windsurf/Cursor 不完全支持 "Reopen in Container",解决方案是在 DevContainer 内启动 sshd。
-
postCreateCommand→setup-sshd.sh一次性配置 -
postStartCommand→start-sshd.sh每次启动拉起 sshd
sshd 配置: 端口 2222、禁用密码登录、禁用 root 登录、限制用户 developer
# 测试连接 ssh -p 2222 developer@127.0.0.1 # Windsurf/Cursor Remote-SSH 配置 # Host: 127.0.0.1, Port: 2222, User: developer, 工作目录: /workspace
| 环境变量 | 默认值 | 说明 |
|---|---|---|
FASTQTOOLS_SSH_BIND |
127.0.0.1 |
绑定地址 |
FASTQTOOLS_SSH_PORT |
2222 |
SSH 端口 |
# 构建生产镜像 ./scripts/tools/deploy --env production --action build # 运行 ./scripts/tools/deploy --env production --action run # docker-compose docker-compose -f docker/docker-compose.yml up -d prod
./scripts/tools/deploy --env development --action run
# 或 VS Code → Ctrl+Shift+P → "Reopen in Container"# 构建 + 测试 ./scripts/tools/deploy --env test --action run # 推送到镜像仓库 ./scripts/tools/deploy --action push --registry your-registry.com/fastqtools --tag v3.1.0
| 项目 | 值 |
|---|---|
| 基础 | debian:bookworm-slim |
| 大小 | ~100MB |
| 内容 | FastQTools 二进制 + 运行时库 |
| 用户 | 非 root(fastqtools:1000) |
| 健康检查 | fastqtools --help || exit 1 |
| 项目 | 值 |
|---|---|
| 基础 | gcc:15.2-bookworm |
| 大小 | ~2GB |
| 内容 | 完整开发工具链 |
| 用户 | 非 root(developer:1000) |
volumes: - ./data:/app/data:ro # 只读输入 - ./output:/app/output # 可写输出
volumes: - ..:/workspace:cached # 源码 - ~/.conan2:/home/developer/.conan2:cached # Conan 缓存 - ~/.ccache:/home/developer/.ccache:cached # 构建缓存
# 生产环境 FASTQTOOLS_DATA_DIR=/app/data FASTQTOOLS_OUTPUT_DIR=/app/output # 开发环境 CC=clang CXX=clang++ CONAN_HOME=/home/developer/.conan2 CCACHE_DIR=/home/developer/.ccache
- 非 root 用户运行(UID 1000)
- 最小化基础镜像
- 只读输入卷
- 多阶段构建减小攻击面
- 非 root + sudo
- SSH Agent 转发
- sshd 默认只绑定
127.0.0.1 - 禁用密码登录,仅公钥认证
| 技术 | 效果 |
|---|---|
| ccache | 增量构建缓存 |
| Ninja | 并行构建 |
| Conan 缓存卷 | 避免重复编译依赖 |
| 多阶段构建 | 减小生产镜像体积 |
| Release 构建 | -O3 -march=native |
| 问题 | 解决 |
|---|---|
| SSH Agent 未检测到 | WSL 中 eval "$(ssh-agent -s)" && ssh-add,然后 Rebuild Container |
| Git Permission denied |
ssh-add -l 确认 key 已加载 |
| SSH Connection refused | 检查容器状态和端口映射: docker port fastqtools-dev
|
| 性能很慢 | 确认仓库在 WSL2 Linux 文件系统下(不是 Windows 盘符) |
| Permission Denied | sudo chown -R 1000:1000 ./data ./output |
| 缺少依赖库 | docker exec <container> ldd /usr/local/bin/FastQTools |
# 手动启动容器 docker start fastqtools-dev # 手动启动 sshd docker exec fastqtools-dev bash /workspace/.devcontainer/scripts/start-sshd.sh # SSH 连接 ssh -p 2222 developer@localhost # 健康检查 docker exec fastqtools-prod FastQTools --help # 查看日志 docker logs -f fastqtools-prod
- 构建新版本镜像
- 停止旧容器
- 使用相同卷启动新容器
- 验证功能
- 删除旧镜像
- 使用具体版本标签,不用
latest - 设置 CPU/内存资源限制
- 尽可能使用只读根文件系统
- 定期更新基础镜像
- 监控容器资源使用
- Getting Started — 环境搭建
- Build and CI — 构建系统
- Contributing Guide — 开发流程
FastQTools v3.1.0
🚀 快速上手
🏗️ 架构与设计
🔧 构建与部署
🧪 质量工程
📖 规范与参考
🔗 外部链接