告别Docker Compose：在Windows上手动搭建Dify的本地开发环境（PostgreSQL+Redis+Weaviate）

告别Docker Compose在Windows上手动搭建Dify的本地开发环境PostgreSQLRedisWeaviate对于希望深入理解Dify架构的开发者来说一键式的Docker Compose部署虽然便捷却像黑箱一样隐藏了关键细节。本文将带你从零开始在Windows系统上手动搭建PostgreSQL、Redis和Weaviate服务并配置Dify各组件与这些中间件的连接打造一个完全透明、便于调试的开发环境。1. 环境准备与中间件安装1.1 获取Dify源码与Python环境配置首先从GitHub克隆最新版Dify源码git clone https://github.com/langgenius/dify.git建议使用Python 3.12版本可通过以下命令检查当前Python版本python --version如果尚未安装合适版本推荐从Python官网下载安装包。安装完成后建议创建专用虚拟环境# 创建并激活虚拟环境 python -m venv .venv .\.venv\Scripts\activate1.2 手动安装PostgreSQL从PostgreSQL官网下载Windows版本安装包安装时记住设置的超级用户密码安装完成后使用pgAdmin或psql创建Dify专用数据库CREATE DATABASE dify; CREATE USER dify_user WITH PASSWORD your_secure_password; GRANT ALL PRIVILEGES ON DATABASE dify TO dify_user;关键配置参数建议编码UTF-8连接数至少50共享缓冲区建议设置为系统内存的25%1.3 手动安装Redis下载Redis for Windows最新版本解压后修改redis.windows.conf配置文件maxmemory 1GB maxmemory-policy allkeys-lru bind 127.0.0.1 requirepass your_redis_password启动Redis服务redis-server.exe redis.windows.conf1.4 手动安装WeaviateWeaviate官方推荐使用Docker运行但我们可以通过源码安装下载Weaviate二进制文件创建配置文件config.yamlpersistence: dataPath: ./data services: weaviate: image: semitechnologies/weaviate:latest ports: - 8080:8080 environment: QUERY_DEFAULTS_LIMIT: 25 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: true PERSISTENCE_DATA_PATH: ./data启动服务weaviate-server --config config.yaml2. Dify服务端配置与启动2.1 环境变量配置进入api目录复制并修改.env文件cd dify/api cp .env.example .env关键配置项修改# 数据库配置 DB_HOSTlocalhost DB_PORT5432 DB_USERdify_user DB_PASSWORDyour_secure_password DB_NAMEdify # Redis配置 REDIS_HOSTlocalhost REDIS_PORT6379 REDIS_PASSWORDyour_redis_password # Weaviate配置 WEAVIATE_URLhttp://localhost:8080生成安全密钥$secretKey -join ((65..90) (97..122) (48..57) | Get-Random -Count 64 | % {[char]$_}) (Get-Content .env) -replace ^SECRET_KEY.*, SECRET_KEY$secretKey | Set-Content .env2.2 依赖安装与数据库迁移使用Poetry安装依赖poetry install如果遇到Microsoft Visual C 14.0缺失错误需要安装Visual C Build Tools。执行数据库迁移poetry run flask db upgrade2.3 启动API服务poetry run flask run --host 0.0.0.0 --port5001 --debug常见问题解决如果遇到gevent兼容性问题尝试pip install -U --force-reinstall --no-binary :all: gevent端口冲突时修改.env中的API_PORT值3. Worker服务配置与启动3.1 Windows专用配置由于Windows对Celery的支持限制需要使用特殊参数celery -A app.celery worker -P solo --without-gossip --without-mingle -Q dataset,generation,mail,ops_trace --loglevel INFO关键参数说明-P solo: Windows下必须使用的池策略--without-gossip/--without-mingle: 禁用不兼容的功能-Q: 指定监听的队列3.2 任务队列监控可以通过flower监控任务队列pip install flower celery -A app.celery flower --port5555访问http://localhost:5555即可查看任务执行情况。4. 前端服务部署与调试4.1 环境准备确保已安装Node.js v18.x和npm 8.xnode -v npm -v4.2 前端配置进入web目录并安装依赖cd ../web npm install创建.env.local文件并配置API端点NEXT_PUBLIC_API_PREFIXhttp://localhost:5001/console/api NEXT_PUBLIC_PUBLIC_API_PREFIXhttp://localhost:5001/api4.3 开发模式启动npm run dev这种模式下支持热重载适合前端调试。4.4 生产构建与启动npm run build npm run start构建优化建议使用NEXT_PUBLIC_DEPLOY_ENVPRODUCTION提升性能配置合适的缓存策略启用Gzip压缩5. 系统联调与问题排查5.1 组件连通性测试使用以下命令测试各服务连通性# 测试PostgreSQL psql -h localhost -U dify_user -d dify -c SELECT 1 # 测试Redis redis-cli -h localhost -p 6379 -a your_redis_password PING # 测试Weaviate curl http://localhost:8080/v1/meta5.2 常见问题解决方案数据库连接失败检查PostgreSQL的pg_hba.conf文件确保允许本地连接验证防火墙是否放行了5432端口Redis响应缓慢检查内存使用情况redis-cli info memory考虑增加maxmemory配置Weaviate向量搜索异常检查服务日志journalctl -u weaviate -f验证schema是否正常创建跨服务认证问题确保所有服务使用的SECRET_KEY一致检查各服务的系统时间是否同步5.3 性能优化建议数据库优化为常用查询创建索引定期执行VACUUM ANALYZE调整shared_buffers和work_mem参数Redis优化启用持久化合理设置过期时间使用pipeline批量操作Weaviate优化根据数据量调整ef和efConstruction参数定期压缩向量索引6. 开发调试技巧6.1 API调试使用Postman或curl测试API# 创建应用示例 curl -X POST http://localhost:5001/console/api/apps \ -H Authorization: Bearer your_api_key \ -H Content-Type: application/json \ -d {name:Test App,mode:chat}6.2 日志查看各组件日志位置API服务直接显示在控制台或查看logs/api.logWorker服务logs/celery.log前端浏览器开发者工具控制台6.3 断点调试在VS Code中配置launch.json{ version: 0.2.0, configurations: [ { name: Python: Flask, type: python, request: launch, module: flask, env: { FLASK_APP: app.py, FLASK_ENV: development }, args: [run, --host0.0.0.0, --port5001, --no-debugger, --no-reload], jinja: true } ] }6.4 数据库迁移管理创建新迁移poetry run flask db migrate -m your migration message回滚迁移poetry run flask db downgrade7. 进阶配置与扩展7.1 多环境配置管理建议创建不同环境的配置文件.env.development.env.testing.env.production通过环境变量加载对应配置$env:FLASK_ENVdevelopment poetry run flask run7.2 自定义中间件如需替换默认中间件修改相应配置# 使用MySQL替代PostgreSQL DB_ENGINEmysql DB_HOSTmysql_host DB_PORT3306 # 使用Elasticsearch替代Weaviate SEARCH_ENGINEelasticsearch ELASTICSEARCH_HOSTlocalhost7.3 插件开发支持Dify支持通过插件扩展功能。创建插件的基本步骤在api/plugins目录下创建新插件文件夹实现必要的接口from extensions.ext_plugin import PluginBase class MyPlugin(PluginBase): def setup(self): # 初始化逻辑 pass在.env中启用插件ENABLED_PLUGINSmy_plugin7.4 监控与告警建议配置以下监控项API响应时间与错误率数据库连接池使用情况队列积压任务数系统资源使用率可以使用PrometheusGrafana搭建监控面板相关指标端点/metricsAPI服务指标/flower/metricsCelery工作指标