WiseFlow部署实战：从零搭建到避坑指南

1. WiseFlow部署前的准备工作在开始部署WiseFlow之前我们需要做好充分的准备工作。首先确保你的开发环境满足以下基本要求操作系统Windows 10/11、macOS 10.15或主流Linux发行版内存建议8GB以上存储空间至少10GB可用空间Docker版本20.10.0我强烈推荐使用Docker进行部署这能最大程度避免环境差异带来的问题。如果你在国内可能会遇到Docker镜像拉取慢的问题可以配置国内镜像源加速# 创建或修改Docker配置文件 sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [https://docker.mirrors.ustc.edu.cn] } EOF # 重启Docker服务 sudo systemctl daemon-reload sudo systemctl restart docker2. 获取WiseFlow项目代码获取项目代码是部署的第一步这里有几个关键点需要注意# 克隆项目仓库 git clone https://github.com/TeamWiseFlow/wiseflow.git cd wiseflow克隆完成后我建议先检查项目结构。WiseFlow的典型目录结构应该包含core/核心业务逻辑代码pb/PocketBase相关文件scripts/各种辅助脚本compose.yamlDocker编排文件特别注意项目根目录下可能没有Dockerfile这是正常现象因为项目使用Docker Compose进行多容器管理。3. 配置环境变量环境变量配置是部署过程中最容易出错的部分。我们需要创建.env文件# 从模板创建.env文件 cp env_sample .env然后编辑.env文件以下是最关键的几个配置项# PocketBase配置 POCKETBASE_URLhttp://127.0.0.1:8090 POCKETBASE_PORT8090 PB_API_AUTHadminexample.com:yourpassword # 可选的大模型API配置 # LLM_API_KEYsk-your-api-key我在实际部署中发现PB_API_AUTH的格式必须是邮箱:密码而且邮箱必须真实有效否则后续会遇到认证问题。4. 使用Docker Compose启动服务现在可以启动服务了但有几个坑需要注意docker compose up -d第一次运行时你会看到PocketBase容器启动失败这是正常现象因为此时还没有创建管理员账号。保持容器运行状态然后访问 http://127.0.0.1:8090/_/按照提示创建管理员账号必须使用真实邮箱将创建的邮箱和密码更新到.env文件的PB_API_AUTH中重启容器docker compose restart我在测试中发现有时PocketBase会占用8090端口导致冲突。如果遇到这个问题可以# 查找占用端口的进程 sudo lsof -i :8090 # 终止相关进程 kill -9 PID5. 常见问题排查5.1 PocketBase端口冲突如果8090端口被占用可以修改PocketBase的监听端口修改compose.yaml中PocketBase服务的端口映射同步更新.env中的POCKETBASE_URL和POCKETBASE_PORT重新创建容器docker compose up -d --force-recreate5.2 缺少Python依赖如果遇到Python依赖问题可以手动安装# 进入core目录 cd core # 创建虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装依赖 pip install -r requirements.txt5.3 脚本执行权限问题在Linux/macOS下可能会遇到脚本权限问题chmod x scripts/*.sh在Windows下可以通过Git Bash来执行这些脚本。6. 系统配置优化为了让WiseFlow运行更稳定我建议进行以下优化时区设置在compose.yaml中添加时区环境变量environment: - TZAsia/Shanghai资源限制为容器设置合理的资源限制deploy: resources: limits: cpus: 2 memory: 4G日志轮转配置日志文件大小限制logging: options: max-size: 10m max-file: 37. 生产环境部署建议如果你要将WiseFlow部署到生产环境还需要考虑数据库持久化确保pb_data目录被正确挂载volumes: - ./pb_data:/pb/pb_dataHTTPS配置使用Nginx反向代理并配置SSL证书定期备份设置pb_data目录的自动备份机制监控告警配置容器健康检查和性能监控我在实际项目中发现定期清理PocketBase的日志文件也很重要可以通过cronjob设置定期清理任务# 每周日凌晨3点清理日志 0 3 * * 0 find /path/to/pb_data/logs -type f -mtime 7 -delete8. 进阶配置技巧8.1 多环境配置管理对于开发、测试、生产等多环境我建议使用不同的compose文件# 开发环境 docker compose -f compose-dev.yaml up # 生产环境 docker compose -f compose-prod.yaml up8.2 自定义PocketBase配置你可以通过挂载自定义配置文件来修改PocketBase行为volumes: - ./custom/pocketbase.ini:/pb/pocketbase.ini8.3 性能调优对于高负载场景可以调整这些参数[server] max_open_conns 100 pool_size 209. 备份与恢复策略数据安全至关重要以下是推荐的备份方案定期全量备份# 备份pb_data目录 tar -czvf pb_data_backup_$(date %Y%m%d).tar.gz pb_data增量备份设置PocketBase的自动备份功能云存储备份将备份文件同步到云存储恢复数据时只需停止服务替换pb_data目录然后重启容器即可。10. 日常维护建议经过多次部署和维护我总结出以下经验版本升级先备份再升级遵循小版本逐步升级原则日志分析定期检查容器日志及时发现潜在问题资源监控使用docker stats监控容器资源使用情况安全更新定期更新基础镜像和安全补丁一个实用的维护脚本示例#!/bin/bash # 每日维护任务 docker system prune -f docker image prune -a -f find /var/lib/docker/containers -type f -name *.log -size 100M -delete