Hair Keeper v1.0.0：一个高度集成、深度定制、约定优于配置的全栈Web应用模板，旨在保持灵活性的同时提供一套基于成熟架构的开发底座，自带身份认证、权限控制、丰富前端组件、文件上传、后台任务、智能体开发等丰富功能，提供AI开发辅助，免于纠结功能如何实现，可快速上手专注于业务逻辑
This commit is contained in:
335
.cloud-dev/README.md
Normal file
335
.cloud-dev/README.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 云开发容器
|
||||
|
||||
本目录包含 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
|
||||
Reference in New Issue
Block a user