335 lines
8.0 KiB
Markdown
335 lines
8.0 KiB
Markdown
# 云开发容器
|
||
|
||
本目录包含 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（推荐）
|
||
|
||
#### 使用默认密码启动
|
||
```zsh
|
||
cd .cloud-dev
|
||
docker compose up -d
|
||
```
|
||
|
||
#### 自定义密码启动
|
||
修改 `docker-compose.yml` 中的 `DEV_PASSWORD` 环境变量，或使用环境变量覆盖：
|
||
```zsh
|
||
DEV_PASSWORD=your_password docker compose up -d
|
||
```
|
||
|
||
停止容器：
|
||
```zsh
|
||
docker compose down
|
||
```
|
||
|
||
查看日志：
|
||
```zsh
|
||
docker compose logs -f
|
||
```
|
||
|
||
重新构建：
|
||
```zsh
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 方式二：使用 Docker 命令
|
||
|
||
#### 1. 构建镜像
|
||
|
||
```zsh
|
||
cd .cloud-dev
|
||
docker build -t hair-keeper-dev .
|
||
```
|
||
|
||
#### 2. 运行容器
|
||
|
||
使用默认密码：
|
||
```zsh
|
||
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
|
||
```
|
||
|
||
使用自定义密码：
|
||
```zsh
|
||
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 连接
|
||
```zsh
|
||
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 终端) 默认不启动，如需使用可在容器内手动运行：
|
||
```zsh
|
||
ttyd -p 7681 zsh
|
||
```
|
||
然后通过 http://localhost:7681 访问（需要在 docker run 或 docker-compose.yml 中映射 7681 端口）
|
||
|
||
## 🔧 常用操作
|
||
|
||
### 进入容器
|
||
```zsh
|
||
docker exec -it hair-keeper-dev zsh
|
||
```
|
||
|
||
### 安装项目依赖
|
||
```zsh
|
||
docker exec -it hair-keeper-dev pnpm install
|
||
```
|
||
|
||
### 启动开发服务器
|
||
```zsh
|
||
docker exec -it hair-keeper-dev pnpm run dev
|
||
```
|
||
|
||
### 查看容器日志
|
||
```zsh
|
||
docker logs -f hair-keeper-dev
|
||
```
|
||
|
||
### 查看 Code Server 日志
|
||
Code Server 的日志位于容器内的 `/root/.local/share/code-server/coder-logs/` 目录，包含两个日志文件：
|
||
|
||
```zsh
|
||
# 查看日志文件列表
|
||
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
|
||
```
|
||
|
||
### 停止容器
|
||
```zsh
|
||
docker stop hair-keeper-dev
|
||
```
|
||
|
||
### 删除容器
|
||
```zsh
|
||
docker rm hair-keeper-dev
|
||
```
|
||
|
||
## 🎯 工作流程
|
||
|
||
1. **启动容器**: 运行上述 docker run 命令
|
||
2. **访问 Code Server**: 在浏览器打开 http://localhost:8080
|
||
3. **打开项目**: Code Server 会自动打开 /workspace 目录（映射到项目根目录）
|
||
4. **安装依赖**: 在终端运行 `pnpm install`
|
||
5. **启动开发**: 运行 `pnpm run dev`
|
||
6. **开始开发**: 在浏览器访问 http://localhost:3000
|
||
|
||
## 💡 提示
|
||
|
||
### Shell 环境
|
||
容器默认使用 **zsh** 作为 Shell，配置了 **oh-my-zsh** 框架：
|
||
- 主题：robbyrussell
|
||
- 插件：git, node, npm, docker, python
|
||
- 自动补全和语法高亮
|
||
- 更友好的命令行体验
|
||
|
||
### Python 包管理
|
||
推荐使用 **uv** 进行 Python 包管理，它比 pip 快得多：
|
||
```zsh
|
||
# 创建虚拟环境
|
||
uv venv
|
||
|
||
# 安装包
|
||
uv pip install package-name
|
||
|
||
# 从 requirements.txt 安装
|
||
uv pip install -r requirements.txt
|
||
```
|
||
|
||
### 数据持久化
|
||
- 项目代码通过 volume 映射，修改会实时同步到主机
|
||
- node_modules 建议使用 Docker volume 以提高性能
|
||
|
||
### 性能优化
|
||
如果需要更好的性能，可以使用命名卷：
|
||
|
||
```zsh
|
||
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
|
||
```
|
||
|
||
### 运行时修改密码
|
||
如果需要在容器运行时修改密码：
|
||
|
||
**方法一：重启容器并设置新密码**
|
||
```zsh
|
||
docker stop hair-keeper-dev
|
||
docker rm hair-keeper-dev
|
||
# 使用新密码重新启动
|
||
DEV_PASSWORD=new_password docker compose up -d
|
||
```
|
||
|
||
**方法二：在容器内手动修改**
|
||
```zsh
|
||
# 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`：
|
||
```yaml
|
||
environment:
|
||
- DEV_PASSWORD=your_secure_password
|
||
```
|
||
|
||
**Docker 命令方式**：
|
||
```zsh
|
||
docker run -e DEV_PASSWORD=your_secure_password ...
|
||
```
|
||
|
||
### 安全建议
|
||
- ⚠️ 生产环境务必修改默认密码
|
||
- 建议使用 SSH 密钥认证替代密码
|
||
- 不要将容器直接暴露到公网
|
||
- 使用反向代理（如 Nginx）并配置 HTTPS
|
||
- 定期更换密码
|
||
|
||
## 📚 相关资源
|
||
|
||
- [Code Server 文档](https://coder.com/docs/code-server)
|
||
- [Docker 文档](https://docs.docker.com/)
|
||
- [tmux 快捷键](https://tmuxcheatsheet.com/)
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 端口被占用
|
||
如果端口被占用，可以修改主机端口映射：
|
||
```zsh
|
||
-p 8081:8080 # 将 Code Server 映射到 8081
|
||
```
|
||
|
||
### 权限问题
|
||
如果遇到文件权限问题，确保容器内的用户有正确的权限：
|
||
```zsh
|
||
docker exec -it hair-keeper-dev chown -R root:root /workspace
|
||
```
|
||
|
||
### 容器无法启动
|
||
查看容器日志排查问题：
|
||
```zsh
|
||
docker logs hair-keeper-dev |