admin/hair-keeper
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2a80a449720992047affd4b9912eeb662b230a82
hair-keeper/.cloud-dev/README.md

8.0 KiB
Raw Blame History

云开发容器

本目录包含 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 开发服务器

📝 端口映射

服务 容器端口 主机端口 说明
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

🎯 工作流程

  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 快得多：

# 创建虚拟环境
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
Reference in New Issue View Git Blame Copy Permalink