云开发容器
本目录包含 Hair Keeper 项目的云开发容器配置，提供完整的开发环境，无需在本地安装任何开发工具。
📦 容器内容
开发环境
- Node.js: 22.14.0
- pnpm: 最新版本
- Python: 3.12
- Code Server: 4.96.2 (基于 VS Code 的 Web IDE)
- Git: 版本控制工具
Shell 环境
- zsh: 默认 Shell
- oh-my-zsh: zsh 配置框架
- tmux: 终端复用器
命令行工具
- ttyd: Web 终端（可选启动）
- tree: 目录树显示
- pwgen: 密码生成器
- curl/wget: 下载工具
- ffmpeg: 多媒体处理
- mc: MinIO 客户端
- zip/unzip: 压缩工具
- net-tools: 网络工具
- ssh: 远程连接
- cmake: 构建工具
- telnet: 网络调试
- redis-tools: Redis 命令行工具
- potrace: 位图转矢量图
- imagemagick: 图像处理工具
- uv: 快速 Python 包管理器
NPM 全局包
@anthropic-ai/claude-code: Claude AI 代码助手@musistudio/claude-code-router: Claude 代码路由器
VS Code 插件
- vscode-pdf: PDF 查看器
- Markdown Preview Mermaid Support: Mermaid 图表支持
- Python: Python 语言支持
- Roo Code: Roo 代码助手
- ESLint: JavaScript/TypeScript 代码检查
- HTML Preview: HTML 预览
- Prisma: Prisma ORM 支持
- HTML CSS Support: HTML/CSS 智能提示
- Redis: Redis 客户端
🚀 使用方法
方式一：使用 Docker Compose（推荐）
使用默认密码启动
cd .cloud-dev
docker compose up -d
自定义密码启动
修改 docker-compose.yml 中的 DEV_PASSWORD 环境变量，或使用环境变量覆盖：
DEV_PASSWORD=your_password docker compose up -d
停止容器：
docker compose down
查看日志：
docker compose logs -f
重新构建：
docker compose up -d --build
方式二：使用 Docker 命令
1. 构建镜像
cd .cloud-dev
docker build -t hair-keeper-dev .
2. 运行容器
使用默认密码：
docker run -d \
--name hair-keeper-dev \
-p 2222:22 \
-p 8080:8080 \
-p 7681:7681 \
-p 3000:3000 \
-v $(pwd)/..:/workspace:cached \
-v hair-keeper-node-modules:/workspace/node_modules \
-v hair-keeper-pnpm-store:/root/.local/share/pnpm/store \
hair-keeper-dev
使用自定义密码：
docker run -d \
--name hair-keeper-dev \
-e DEV_PASSWORD=your_password \
-p 2222:22 \
-p 8080:8080 \
-p 7681:7681 \
-p 3000:3000 \
-v $(pwd)/..:/workspace:cached \
-v hair-keeper-node-modules:/workspace/node_modules \
-v hair-keeper-pnpm-store:/root/.local/share/pnpm/store \
hair-keeper-dev
3. 访问开发环境
容器启动后，可以通过以下方式访问：
Code Server (Web IDE)
- 地址: http://localhost:8080
- 默认密码:
clouddev（可通过DEV_PASSWORD环境变量自定义） - 提供完整的 VS Code 开发体验
- 内置终端使用 zsh + oh-my-zsh
SSH 连接
ssh root@localhost -p 2222
# 默认密码: clouddev（可通过 DEV_PASSWORD 环境变量自定义）
Next.js 开发服务器
- 地址: http://localhost:3000
- 在容器内运行
pnpm run dev启动
📝 端口映射
| 服务 | 容器端口 | 主机端口 | 说明 |
|---|---|---|---|
| SSH | 22 | 2222 | SSH 远程连接 |
| Code Server | 8080 | 8080 | Web IDE |
| Next.js | 3000 | 3000 | 开发服务器 |
注意: ttyd (Web 终端) 默认不启动，如需使用可在容器内手动运行：
ttyd -p 7681 zsh
然后通过 http://localhost:7681 访问（需要在 docker run 或 docker-compose.yml 中映射 7681 端口）
🔧 常用操作
进入容器
docker exec -it hair-keeper-dev zsh
安装项目依赖
docker exec -it hair-keeper-dev pnpm install
启动开发服务器
docker exec -it hair-keeper-dev pnpm run dev
查看容器日志
docker logs -f hair-keeper-dev
查看 Code Server 日志
Code Server 的日志位于容器内的 /root/.local/share/code-server/coder-logs/ 目录，包含两个日志文件：
# 查看日志文件列表
docker exec -it hair-keeper-dev ls -lt /root/.local/share/code-server/coder-logs/
# 实时查看标准输出日志
docker exec -it hair-keeper-dev tail -f /root/.local/share/code-server/coder-logs/code-server-stdout.log
# 实时查看错误日志
docker exec -it hair-keeper-dev tail -f /root/.local/share/code-server/coder-logs/code-server-stderr.log
# 同时查看两个日志文件
docker exec -it hair-keeper-dev tail -f /root/.local/share/code-server/coder-logs/code-server-*.log
# 或者在容器内查看
docker exec -it hair-keeper-dev zsh
cd /root/.local/share/code-server/coder-logs/
tail -f code-server-stdout.log code-server-stderr.log
停止容器
docker stop hair-keeper-dev
删除容器
docker rm hair-keeper-dev
🎯 工作流程
- 启动容器: 运行上述 docker run 命令
- 访问 Code Server: 在浏览器打开 http://localhost:8080
- 打开项目: Code Server 会自动打开 /workspace 目录（映射到项目根目录）
- 安装依赖: 在终端运行
pnpm install - 启动开发: 运行
pnpm run dev - 开始开发: 在浏览器访问 http://localhost:3000
💡 提示
Shell 环境
容器默认使用 zsh 作为 Shell，配置了 oh-my-zsh 框架：
- 主题：robbyrussell
- 插件：git, node, npm, docker, python
- 自动补全和语法高亮
- 更友好的命令行体验
Python 包管理
推荐使用 uv 进行 Python 包管理，它比 pip 快得多：
# 创建虚拟环境
uv venv
# 安装包
uv pip install package-name
# 从 requirements.txt 安装
uv pip install -r requirements.txt
数据持久化
- 项目代码通过 volume 映射，修改会实时同步到主机
- node_modules 建议使用 Docker volume 以提高性能
性能优化
如果需要更好的性能，可以使用命名卷：
docker volume create hair-keeper-node-modules
docker run -d \
--name hair-keeper-dev \
-p 2222:22 \
-p 8080:8080 \
-p 7681:7681 \
-p 3000:3000 \
-v $(pwd)/..:/workspace \
-v hair-keeper-node-modules:/workspace/node_modules \
hair-keeper-dev
运行时修改密码
如果需要在容器运行时修改密码：
方法一：重启容器并设置新密码
docker stop hair-keeper-dev
docker rm hair-keeper-dev
# 使用新密码重新启动
DEV_PASSWORD=new_password docker compose up -d
方法二：在容器内手动修改
# SSH 密码
docker exec -it hair-keeper-dev passwd
# Code Server 密码
docker exec -it hair-keeper-dev zsh -c "echo 'password: new_password' >> /root/.config/code-server/config.yaml"
# 然后重启 code-server
🔐 密码配置
默认密码
容器默认密码为 clouddev，用于：
- SSH 登录（root 用户）
- Code Server Web IDE
自定义密码
通过环境变量 DEV_PASSWORD 设置自定义密码：
Docker Compose 方式：
编辑 docker-compose.yml：
environment:
- DEV_PASSWORD=your_secure_password
Docker 命令方式：
docker run -e DEV_PASSWORD=your_secure_password ...
安全建议
- ⚠️ 生产环境务必修改默认密码
- 建议使用 SSH 密钥认证替代密码
- 不要将容器直接暴露到公网
- 使用反向代理（如 Nginx）并配置 HTTPS
- 定期更换密码
📚 相关资源
🐛 故障排除
端口被占用
如果端口被占用，可以修改主机端口映射：
-p 8081:8080 # 将 Code Server 映射到 8081
权限问题
如果遇到文件权限问题，确保容器内的用户有正确的权限：
docker exec -it hair-keeper-dev chown -R root:root /workspace
容器无法启动
查看容器日志排查问题：
docker logs hair-keeper-dev