开源项目Hocus安装与配置指南
项目地址: https://gitcode.com/gh_mirrors/ho/hocus 🧙♂️ 什么是Hocus？
Hocus是一个自托管的开发环境解决方案，能够在自己的服务器上快速启动即用型、可丢弃的开发环境。它类似于Gitpod和GitHub Codespaces，但完全自托管，让你拥有完全的控制权。
通过Hocus，你可以：
- 🚀 在几秒钟内启动完整的开发环境
- 🔧 将开发环境定义为代码（Infrastructure as Code）
- 🤝 支持团队协作和共享环境变量
- 💻 获得完整的root访问权限（完整虚拟机）
- 🔗 集成任何支持SSH协议的Git提供商
📋 系统要求
在开始安装之前，请确保你的系统满足以下要求：
硬件要求
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | x86_64架构，支持KVM | 多核心处理器 |
| 内存 | 8GB RAM | 16GB+ RAM |
| 存储 | 50GB可用空间 | 100GB+ SSD |
| 网络 | 稳定的互联网连接 | 千兆网络 |
软件要求
# 操作系统要求
- x86_64 Linux系统（推荐内核版本≥5.10）
- 支持KVM虚拟化
- 支持target_core_user、tcm_loop和sd_mod内核模块
# 必需软件
- Git
- Docker
- Docker Compose（≥2.15.0）
- Docker Buildx
内核模块检查
# 检查KVM支持
sudo apt-get install cpu-checker
kvm-ok
# 检查必需内核模块
lsmod | grep -E "target_core_user|tcm_loop|sd_mod"
🚀 安装步骤
步骤1：克隆仓库
git clone https://gitcode.com/gh_mirrors/ho/hocus.git
cd hocus
步骤2：设置环境变量
# 本地部署使用localhost
export HOCUS_HOSTNAME="localhost"
# 远程服务器部署使用服务器域名或IP
# export HOCUS_HOSTNAME="your-server-domain.com"
步骤3：运行安装脚本
# 自动检查系统要求并安装
HOCUS_HOSTNAME="localhost" ops/bin/local-up.sh
安装过程详解
安装脚本会执行以下操作：
⚙️ 服务组件说明
Hocus部署后会启动以下核心服务：
| 服务名称 | 端口 | 功能描述 | 默认凭据 |
|---|---|---|---|
| Hocus控制平面 | 3000 | Web用户界面和API | dev/dev |
| Keycloak认证 | 4200 | 身份认证和用户管理 | admin/admin |
| Temporal工作流引擎 | 8080 | 工作流管理和调度 | - |
| PostgreSQL数据库 | 5432 | 数据存储 | 自动配置 |
| Hocus Agent | - | 工作空间管理 | - |
🔧 配置详解
核心配置文件：hocus.yml
Hocus使用hocus.yml文件来定义开发环境配置：
# hocus.yml 示例配置
image:
file: hocus.Dockerfile
buildContext: ./
tasks:
- name: Control Plane
prebuild: |
yarn install
npm run dev-prebuild
ops/bin/prepare.sh
workspaceShell: fish
workspace: |
npx ts-node -r tsconfig-paths/register entrypoints/utils/generate-hocus-yml-json-schema.ts > hocus.yml.schema.json
ops/bin/up.sh
ops/bin/temporal-up.sh
npm run dev
vscode:
extensions:
- Prisma.prisma
- esbenp.prettier-vscode
- dbaeumer.vscode-eslint
环境变量配置
重要的环境变量包括：
# 必填环境变量
export HOCUS_HOSTNAME="localhost" # 部署主机名
export POSTGRES_PASSWORD="your_password" # 数据库密码
export POSTGRES_USER="postgres" # 数据库用户
# 可选环境变量
export HOCUS_BUILD_COMMIT_HASH=$(git rev-parse HEAD) # 构建版本
export HOCUS_DEV_GIT_NAME=$(git config --get user.name) # Git用户名
export HOCUS_DEV_GIT_EMAIL=$(git config --get user.email) # Git邮箱
🐛 常见问题排查
问题1：KVM不支持
# 检查KVM支持
sudo apt-get install cpu-checker
kvm-ok
# 如果显示KVM不可用，需要启用虚拟化
# 在BIOS中启用VT-x/AMD-V支持
问题2：Docker权限问题
# 将用户添加到docker组
sudo usermod -aG docker $USER
newgrp docker
# 验证Docker访问
docker ps
问题3：内核模块缺失
# 加载必需内核模块
sudo modprobe target_core_user
sudo modprobe tcm_loop
sudo modprobe sd_mod
# 永久启用（添加到/etc/modules）
echo -e "target_core_user\ntcm_loop\nsd_mod" | sudo tee -a /etc/modules
问题4：端口冲突
如果默认端口被占用，可以修改docker-compose配置：
# 修改 ops/docker/docker-compose.yml 中的端口映射
ports:
- "3001:3000" # 将外部端口改为3001
🛠️ 管理命令
启动服务
# 完整启动
HOCUS_HOSTNAME="localhost" ops/bin/local-up.sh
# 仅启动特定服务
./ops/bin/local-cmd.sh up -d hocus-ui
停止服务
# 停止所有服务
./ops/bin/local-cmd.sh down
# 停止特定服务
./ops/bin/local-cmd.sh stop hocus-ui
查看日志
# 查看所有服务日志
./ops/bin/local-cmd.sh logs
# 查看特定服务日志
./ops/bin/local-cmd.sh logs hocus-ui
# 实时日志跟踪
./ops/bin/local-cmd.sh logs -f
清理数据
# 完全清理（删除所有数据）
./ops/bin/local-cleanup.sh
# 仅删除数据库数据
docker volume prune
📊 性能优化建议
数据库优化
# 在docker-compose中调整PostgreSQL配置
command: postgres -c 'max_connections=10000' -c 'shared_buffers=2GB' -c 'effective_cache_size=6GB'
资源分配调整
根据服务器配置调整资源限制：
# 在docker-compose.yml中调整资源限制
deploy:
resources:
limits:
memory: 8G
cpus: '4'
存储优化
# 使用高性能存储
volumes:
- /ssd-data:/var/lib/docker
# 启用tmpfs用于临时文件
tmpfs:
- /tmp
🔐 安全配置
修改默认凭据
安装后立即修改默认凭据：
# 修改Keycloak管理员密码
访问 http://localhost:4200 → 管理员 → 用户 → 修改admin用户密码
# 修改Hocus默认用户密码
访问 http://localhost:3000 → 使用dev/dev登录 → 用户设置 → 修改密码
启用HTTPS
对于生产环境，建议启用HTTPS：
# 使用反向代理（Nginx示例）
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
}
}
📈 监控和维护
健康检查
# 检查服务状态
./ops/bin/local-cmd.sh ps
# 检查服务健康状态
./ops/bin/local-cmd.sh logs --tail=100 | grep -i error
# 数据库连接检查
docker exec -it hocus-db psql -U postgres -c "\l"
备份策略
# 数据库备份
docker exec hocus-db pg_dump -U postgres rooms > backup_$(date +%Y%m%d).sql
# 配置文件备份
tar -czf hocus_config_backup_$(date +%Y%m%d).tar.gz hocus.yml ops/docker/
🎯 下一步操作
安装完成后，你可以：
- 访问Web界面: http://localhost:3000 (使用dev/dev登录)
- 配置Git集成: 添加你的Git仓库
- 创建第一个工作空间: 体验快速开发环境启动
- 探索高级功能: 预构建、环境变量、团队协作等
💡 最佳实践
- 定期更新: 关注项目更新，定期拉取最新版本
- 监控资源: 使用监控工具跟踪CPU、内存、存储使用情况
- 备份策略: 建立定期备份机制，特别是数据库数据
- 安全审计: 定期进行安全检查和漏洞扫描
- 性能调优: 根据实际使用情况调整资源配置
通过本指南，你应该能够成功安装和配置Hocus，开始享受自托管开发环境带来的便利和灵活性。如果在安装过程中遇到任何问题，建议查看详细日志或参考项目的GitHub Issues页面。
记住，Hocus目前处于alpha阶段，适合个人使用和测试，不建议用于生产环境。随着项目的成熟，它将提供更稳定和强大的功能。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
