# 云开发容器

本目录包含 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