Hair Keeper v1.0.0：一个高度集成、深度定制、约定优于配置的全栈Web应用模板，旨在保持灵活性的同时提供一套基于成熟架构的开发底座，自带身份认证、权限控制、丰富前端组件、文件上传、后台任务、智能体开发等丰富功能，提供AI开发辅助，免于纠结功能如何实现，可快速上手专注于业务逻辑

2025-11-13 15:24:54 +08:00
commit 42be39b343
249 changed files with 38843 additions and 0 deletions
--- a/.cloud-dev/.dockerignore
+++ b/.cloud-dev/.dockerignore
@@ -0,0 +1,55 @@
+# 依赖目录
+node_modules
+.pnpm-store
+
+# 构建输出
+.next
+dist
+build
+out
+
+# 日志文件
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# 环境变量文件
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# 编辑器和 IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+
+# 操作系统文件
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# 测试覆盖率
+coverage
+
+# 临时文件
+tmp
+temp
+*.tmp
+
+# Docker 相关
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# 其他
+.cache
+.turbo
--- a/.cloud-dev/Dockerfile
+++ b/.cloud-dev/Dockerfile
@@ -0,0 +1,141 @@
+FROM ubuntu:22.04
+
+# 设置环境变量
+ENV DEBIAN_FRONTEND=noninteractive \
+    NODE_VERSION=22.14.0 \
+    PYTHON_VERSION=3.12 \
+    CODE_SERVER_VERSION=4.96.2 \
+    LANG=C.UTF-8 \
+    LC_ALL=C.UTF-8 \
+    TZ=Asia/Shanghai \
+    DEV_PASSWORD=clouddev
+
+# 安装基础工具和依赖
+RUN apt-get update && apt-get install -y \
+    curl \
+    wget \
+    git \
+    openssh-server \
+    tmux \
+    tree \
+    pwgen \
+    zip \
+    unzip \
+    net-tools \
+    fontconfig \
+    ffmpeg \
+    ca-certificates \
+    gnupg \
+    lsb-release \
+    build-essential \
+    libssl-dev \
+    zlib1g-dev \
+    libbz2-dev \
+    libreadline-dev \
+    libsqlite3-dev \
+    libncursesw5-dev \
+    xz-utils \
+    tk-dev \
+    libxml2-dev \
+    libxmlsec1-dev \
+    libffi-dev \
+    liblzma-dev \
+    ttyd \
+    cmake \
+    telnet \
+    redis-tools \
+    potrace \
+    imagemagick \
+    zsh \
+    && rm -rf /var/lib/apt/lists/*
+
+# 安装 Python 3.12
+RUN apt-get update && apt-get install -y software-properties-common && \
+    add-apt-repository ppa:deadsnakes/ppa && \
+    apt-get update && \
+    apt-get install -y python3.12 python3.12-venv python3.12-dev python3-pip && \
+    update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1 && \
+    update-alternatives --install /usr/bin/python python /usr/bin/python3.12 1 && \
+    rm -rf /var/lib/apt/lists/*
+
+# 安装 Node.js 22.14
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
+    apt-get install -y nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+# 安装 pnpm
+RUN npm install -g pnpm
+
+# 安装 uv (Python package manager)
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 安装 oh-my-zsh
+RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
+
+# 设置 zsh 为默认 shell
+RUN chsh -s $(which zsh)
+
+# 配置 zsh
+RUN echo 'export ZSH="$HOME/.oh-my-zsh"' > /root/.zshrc && \
+    echo 'ZSH_THEME="robbyrussell"' >> /root/.zshrc && \
+    echo 'plugins=(git node npm docker python)' >> /root/.zshrc && \
+    echo 'source $ZSH/oh-my-zsh.sh' >> /root/.zshrc && \
+    echo '' >> /root/.zshrc && \
+    echo '# 添加 uv 到 PATH' >> /root/.zshrc && \
+    echo 'export PATH="$HOME/.local/bin:$PATH"' >> /root/.zshrc
+
+# 安装 MinIO Client (mc)
+RUN wget https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc && \
+    chmod +x /usr/local/bin/mc
+
+# 安装 code-server
+RUN curl -fsSL https://code-server.dev/install.sh | sh -s -- --version=${CODE_SERVER_VERSION}
+
+# 安装 npm 全局包
+RUN npm install -g \
+    @anthropic-ai/claude-code \
+    @musistudio/claude-code-router
+
+# 创建工作目录
+RUN mkdir -p /workspace /root/.local/share/code-server/User
+
+# 配置 SSH
+RUN mkdir -p /var/run/sshd && \
+    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config && \
+    sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config
+
+# 安装 code-server 插件
+RUN code-server --install-extension ms-ceintl.vscode-language-pack-zh-hans \
+    && code-server --install-extension bierner.markdown-mermaid \
+    && code-server --install-extension ms-python.python \
+    && code-server --install-extension rooveterinaryinc.roo-cline \
+    && code-server --install-extension dbaeumer.vscode-eslint \
+    && code-server --install-extension prisma.prisma \
+    && code-server --install-extension ecmel.vscode-html-css \
+    && code-server --install-extension cweijan.vscode-redis-client
+
+# 配置 code-server (密码将在启动时设置)
+RUN mkdir -p /root/.config/code-server && \
+    echo 'bind-addr: 0.0.0.0:8080' > /root/.config/code-server/config.yaml && \
+    echo 'auth: password' >> /root/.config/code-server/config.yaml && \
+    echo 'cert: false' >> /root/.config/code-server/config.yaml
+
+# 配置 tmux
+RUN echo 'set -g mouse on' > /root/.tmux.conf && \
+    echo 'set -g history-limit 10000' >> /root/.tmux.conf && \
+    echo 'set -g default-terminal "screen-256color"' >> /root/.tmux.conf
+
+# 复制启动脚本
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# 暴露端口
+# 22: SSH
+# 8080: code-server
+# 7681: ttyd
+# 3000: Next.js dev server
+EXPOSE 22 8080 7681 3000
+
+WORKDIR /workspace
+
+ENTRYPOINT ["/entrypoint.sh"]
--- a/.cloud-dev/README.md
+++ b/.cloud-dev/README.md
@@ -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
--- a/.cloud-dev/docker-compose.yml
+++ b/.cloud-dev/docker-compose.yml
@@ -0,0 +1,42 @@
+services:
+  cloud-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: hair-keeper-dev
+    hostname: hair-keeper-dev
+    ports:
+      - "2222:22"      # SSH
+      - "8080:8080"    # Code Server
+      - "7681:7681"    # ttyd (Web Terminal)
+      - "3000:3000"    # Next.js Dev Server
+    volumes:
+      # 项目代码映射（使用 cached 模式提高性能）
+      - ../:/workspace:cached
+      # node_modules 使用命名卷以提高性能
+      - node_modules:/workspace/node_modules
+      # pnpm store 缓存
+      - pnpm_store:/root/.local/share/pnpm/store
+      # Git 配置（可选，如果需要保留 Git 配置）
+      - ~/.gitconfig:/root/.gitconfig:ro
+    environment:
+      - NODE_ENV=development
+      - TZ=Asia/Shanghai
+      # 开发环境密码，可自定义修改
+      - DEV_PASSWORD=clouddev
+    restart: unless-stopped
+    # 资源限制（可选，根据需要调整）
+    deploy:
+      resources:
+        limits:
+          cpus: '4'
+          memory: 8G
+        reservations:
+          cpus: '2'
+          memory: 4G
+
+volumes:
+  # node_modules 卷，避免主机和容器之间的文件系统差异
+  node_modules:
+  # pnpm store 卷，加速依赖安装
+  pnpm_store:
--- a/.cloud-dev/entrypoint.sh
+++ b/.cloud-dev/entrypoint.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# 设置默认密码
+DEV_PASSWORD=${DEV_PASSWORD:-clouddev}
+
+# 设置 root 密码
+echo "root:${DEV_PASSWORD}" | chpasswd
+
+# 确保 code-server 配置目录存在
+mkdir -p /root/.local/share/code-server
+
+# 创建 code-server 配置文件
+cat > /root/.config/code-server/config.yaml << EOF
+bind-addr: 0.0.0.0:8080
+auth: password
+password: ${DEV_PASSWORD}
+cert: false
+EOF
+
+# 启动 SSH 服务
+echo "Starting SSH service..."
+service ssh start
+
+# 启动 code-server
+echo "Starting code-server on port 8080..."
+code-server --bind-addr 0.0.0.0:8080 /workspace &
+
+
+# 输出服务信息
+echo ""
+echo "=========================================="
+echo "Cloud Development Container Started"
+echo "=========================================="
+echo "SSH:         Port 22 (user: root, password: ${DEV_PASSWORD})"
+echo "Code Server: Port 8080 (password: ${DEV_PASSWORD})"
+echo "Next.js Dev: Port 3000 (run 'pnpm run dev' to start)"
+echo "=========================================="
+echo ""
+echo "Workspace: /workspace"
+echo "Default Shell: zsh with oh-my-zsh"
+echo ""
+echo "提示: 可通过环境变量 DEV_PASSWORD 自定义密码"
+echo ""
+
+# 保持容器运行
+tail -f /dev/null