在 Ubuntu 上自托管 Windmill：包含 PostgreSQL 故障排查的完整 Docker 设置教程

工作流自动化平台对现代开发团队至关重要，但随着使用量增长，Windmill Cloud 等云解决方案可能变得昂贵。我们将向您展示如何在 Ubuntu 上使用 Docker Compose 和 Traefik 集成设置自己的 Windmill 实例，同时克服可能导致安装失败的关键 PostgreSQL 身份验证问题。

您将构建的内容

完成本教程后，您将拥有：

带 HTTPS 的完整 Windmill 安装
通过 Traefik 由 Let’s Encrypt 提供的自动 SSL 证书
具有正确身份验证的生产就绪 PostgreSQL 数据库
资源优化的 Worker 配置
与现有 Docker 基础设施的集成
用于专业工作流自动化的生产就绪设置

月度成本： €4.51（CX11 服务器）+ 域名成本 – 同一基础设施可处理多个自动化工具

前提条件

已安装 Docker 和 Docker Compose 的 Ubuntu 24.04 LTS 服务器
现有的 Traefik 反向代理设置（参见我们的 n8n 设置指南了解 Traefik 配置）
指向您服务器 IP 的域名
建议至少 4GB RAM 和 2 个 vCPU
SSH 访问权限和基本命令行知识

了解 Windmill

Windmill 是一个开源工作流引擎，提供：

可视化工作流编辑器，支持 TypeScript/Python/Go
任务调度和执行管理
API 集成能力
团队协作功能
可自托管，无使用限制

与 n8n 基于节点的方法不同，Windmill 专注于代码优先的工作流，配备强大的开发环境。

步骤 1：服务器准备和目录结构

首先，准备服务器环境。我们将使用食物命名约定来避免冲突：

# Create Windmill directory (first instance: "pizza")
mkdir -p /opt/windmill-pizza
cd /opt/windmill-pizza

# Create required subdirectories
mkdir -p postgres-data windmill-data lsp-cache

# Verify directory structure
ls -la

命名约定： 为多个 Windmill 实例使用简单的食物名称：

第一个实例：pizza
额外实例：pasta、salad、soup、burger 等
这可以避免冲突并简化管理

步骤 2：环境配置

使用适当的凭据创建安全的环境文件：

# Generate a secure hex password (no special characters!)
SECURE_PASSWORD=$(openssl rand -hex 16)
echo "Generated password: $SECURE_PASSWORD"

# Create environment file
cat > /opt/windmill-pizza/.env << EOF
# Windmill Image Version
WM_IMAGE=ghcr.io/windmill-labs/windmill:main

# Database Configuration - SECURE PASSWORDS
DATABASE_URL=postgresql://postgres:${SECURE_PASSWORD}@windmill-db:5432/windmill_pizza?sslmode=disable
POSTGRES_PASSWORD=${SECURE_PASSWORD}
POSTGRES_DB=windmill_pizza
POSTGRES_USER=postgres

# Windmill Configuration
BASE_URL=https://windmill.yourdomain.com
RUST_LOG=info

# Worker Configuration
WORKER_GROUP=default
KEEP_JOB_DIR=false

# Instance Identifier
INSTANCE_NAME=pizza
EOF

关键： 将 windmill.yourdomain.com 替换为您的实际域名！

步骤 3：Docker Compose 配置

创建主 Docker Compose 配置：

cat > /opt/windmill-pizza/docker-compose.yml << 'EOF'
version: "3.8"

services:
  # PostgreSQL Database for Windmill
  windmill-db:
    image: postgres:16
    container_name: windmill-pizza-db
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    networks:
      - proxy
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Windmill Server
  windmill-server:
    image: ${WM_IMAGE}
    container_name: windmill-pizza-server
    restart: unless-stopped
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - BASE_URL=${BASE_URL}
      - RUST_LOG=${RUST_LOG}
      - MODE=server
    networks:
      - proxy
    depends_on:
      windmill-db:
        condition: service_healthy
    volumes:
      - ./windmill-data:/tmp/windmill
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.windmill-pizza.rule=Host(`windmill.yourdomain.com`)"
      - "traefik.http.routers.windmill-pizza.entrypoints=https"
      - "traefik.http.routers.windmill-pizza.tls.certresolver=letsencrypt"
      - "traefik.http.services.windmill-pizza.loadbalancer.server.port=8000"

  # Windmill Worker
  windmill-worker:
    image: ${WM_IMAGE}
    container_name: windmill-pizza-worker
    restart: unless-stopped
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - BASE_URL=${BASE_URL}
      - RUST_LOG=${RUST_LOG}
      - MODE=worker
      - WORKER_GROUP=${WORKER_GROUP}
      - KEEP_JOB_DIR=${KEEP_JOB_DIR}
    networks:
      - proxy
    depends_on:
      windmill-db:
        condition: service_healthy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./windmill-data:/tmp/windmill
      - worker_dependency_cache:/tmp/windmill/cache
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 2G

networks:
  proxy:
    external: true

volumes:
  worker_dependency_cache:
    driver: local
EOF

重要： 更新 Traefik 标签中的域名以匹配您的设置！

步骤 4：PostgreSQL 密码问题（关键问题）

这是大多数 Windmill 安装失败的地方，经过大量排查才找到根本原因：

问题：密码中的特殊字符

使用 openssl rand -base64 32 生成密码时，通常会包含 =、@、#、% 等特殊字符。这些字符会导致 Docker 环境中的 PostgreSQL 身份验证失败，即使正确转义也是如此。

有问题的密码示例：

# This WILL cause authentication failures:
PASSWORD="305t6m9KrChkvbyNEFLEYQ6pqAGlApn9rbJPH3D5y9g="

解决方案：纯十六进制密码

使用不含特殊字符的纯十六进制密码：

# This WORKS reliably:
PASSWORD=$(openssl rand -hex 16)
# Example result: 5781b14ec0ec1bc184653ffa5e379411

其他 PostgreSQL 配置问题

用户配置：使用 postgres 作为默认用户，而不是 windmill_user 等自定义用户
卷持久化：当现有数据卷包含不同凭据时，PostgreSQL 会忽略 POSTGRES_PASSWORD 环境变量
URL 格式：在 Docker 环境的数据库 URL 中包含 ?sslmode=disable

步骤 5：安装和启动

现在使用修正后的配置安装 Windmill：

cd /opt/windmill-pizza

# Verify configuration syntax
docker compose config --quiet

# Pull images
docker compose pull

# Start services
docker compose up -d

# Check status
docker compose ps

您应该看到如下输出：

NAME                    STATUS                    PORTS
windmill-pizza-db       Up (healthy)              5432/tcp
windmill-pizza-server   Up                        8000/tcp
windmill-pizza-worker   Up                        8000/tcp

步骤 6：常见问题排查

问题 1：PostgreSQL 身份验证失败

症状：

windmill-pizza-server | Error: password authentication failed for user "postgres"

解决方案：

# Stop containers
docker compose down --volumes

# Remove old data
rm -rf postgres-data/*

# Regenerate hex password
NEW_PASSWORD=$(openssl rand -hex 16)
sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$NEW_PASSWORD/" .env
sed -i "s/:.*@/:$NEW_PASSWORD@/" .env

# Restart
docker compose up -d

问题 2：容器无法启动

症状：

容器立即退出
资源分配错误

解决方案：

# Check container logs
docker logs windmill-pizza-server
docker logs windmill-pizza-db

# Check system resources
docker stats
free -h

问题 3：SSL 证书问题

症状：

HTTPS 不工作
证书错误

解决方案：

# Check Traefik logs
docker logs traefik

# Verify DNS resolution
nslookup windmill.yourdomain.com

# Restart Traefik if needed
docker restart traefik

步骤 7：访问和初始设置

安装完成后：

访问 Windmill： https://windmill.yourdomain.com
默认凭据：
- 邮箱：admin@windmill.dev
- 密码：changeme
完成设置：
- 更改管理员密码
- 配置基础 URL
- 设置用户账户

步骤 8：资源优化

内存分配（8GB 服务器）

我们的配置高效分配资源：

Windmill 服务器：约 800MB
Windmill Worker：2GB（限制）
PostgreSQL：约 500MB
系统保留：约 4.7GB

CPU 分配（4 vCPU 服务器）

Worker：1 vCPU（限制）
其他服务：3 vCPU（共享）

扩展规则： 每个 vCPU 配 1 个 Worker，每个 1-2GB RAM

步骤 9：生产加固

创建备份脚本

cat > /opt/windmill-pizza/backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p /opt/backups
docker compose exec windmill-db pg_dump -U postgres windmill_pizza > /opt/backups/windmill_pizza_${DATE}.sql
echo "Backup created: windmill_pizza_${DATE}.sql"
EOF

chmod +x /opt/windmill-pizza/backup.sh

设置监控

# Monitor container health
docker compose ps

# Check resource usage
docker stats

# Monitor logs
docker compose logs -f windmill-server

配置自动更新

cat > /opt/windmill-pizza/update.sh << 'EOF'
#!/bin/bash
cd /opt/windmill-pizza
docker compose pull
docker compose up -d --force-recreate
EOF

chmod +x /opt/windmill-pizza/update.sh

步骤 10：高级配置

与现有 SMTP 集成

如果您有邮件服务器（如来自我们的 n8n 设置），可以集成：

# Add to docker-compose.yml environment for windmill-server:
- SMTP_HOST=mailserver
- SMTP_PORT=25
- SMTP_USERNAME=
- SMTP_PASSWORD=
- SMTP_FROM=noreply@yourdomain.com

多个 Windmill 实例

对于需要隔离环境的团队：

# Create second instance
cp -r /opt/windmill-pizza /opt/windmill-pasta

# Update configuration
sed -i 's/pizza/pasta/g' /opt/windmill-pasta/.env
sed -i 's/windmill.yourdomain.com/pasta.yourdomain.com/g' /opt/windmill-pasta/.env

# Generate new password
NEW_PASSWORD=$(openssl rand -hex 16)
sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$NEW_PASSWORD/" /opt/windmill-pasta/.env

# Update docker-compose.yml
sed -i 's/pizza/pasta/g' /opt/windmill-pasta/docker-compose.yml
sed -i 's/windmill.yourdomain.com/pasta.yourdomain.com/g' /opt/windmill-pasta/docker-compose.yml

安全考量

网络隔离

PostgreSQL 仅在 Docker 网络内可访问
无外部数据库端口暴露
HTTPS 终止在 Traefik 层

资源限制

Worker 容器有 CPU 和内存限制
防止资源耗尽攻击
可根据服务器容量配置

SSL 安全

自动 Let’s Encrypt 证书
HTTP 到 HTTPS 重定向
现代 TLS 配置

监控与维护

每周健康检查

# Container status
docker compose ps

# Resource usage
docker stats --no-stream

# Log analysis
docker compose logs | grep -i error

每月维护

# Update containers
cd /opt/windmill-pizza
./update.sh

# Clean old data
docker system prune -f

# Backup database
./backup.sh

成本明细与对比

月度成本

自托管设置：

Hetzner CX21（4GB RAM）：€8.46/月
域名成本：约 €1/月
总计：约 €9.50/月

Windmill Cloud 对比：

团队计划：$30/月每用户
节省：小型团队年省 $250+

性能优势

自托管优势：

无限工作流执行
无外部速率限制
完全数据控制
自定义集成
资源扩展灵活性

故障排查参考

快速诊断

# Container health
docker compose ps | grep -E "(healthy|Up)"

# Network connectivity
docker network inspect proxy

# Database connection
docker compose exec windmill-db psql -U postgres -d windmill_pizza -c "SELECT version();"

# Log analysis
docker compose logs --tail 50 windmill-server | grep -E "(ERROR|WARN)"

常见错误模式

“password authentication failed” → 使用十六进制密码，清除卷
“connection refused” → 检查网络配置
“certificate errors” → 验证 DNS 和 Traefik 设置
“out of memory” → 调整 Worker 资源限制

扩展您的 Windmill 基础设施

水平扩展

适用于高负载环境：

# Add additional workers
windmill-worker-2:
  image: ${WM_IMAGE}
  container_name: windmill-pizza-worker-2
  environment:
    - DATABASE_URL=${DATABASE_URL}
    - MODE=worker
    - WORKER_GROUP=heavy
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G

垂直扩展

升级服务器资源：

CX31（8GB RAM）：€16.07/月适用于重负载
CX41（16GB RAM）：€29.75/月适用于企业级使用

与现有基础设施的集成

与 n8n 协同

如果您已在运行 n8n（来自我们之前的教程）：

Windmill 处理代码优先的工作流
n8n 处理可视化的简单自动化
两者共享同一 Traefik 代理
独立数据库防止冲突

共享服务

利用现有基础设施：

Traefik：为所有服务处理 SSL
邮件服务器：共享 SMTP 用于通知
监控：统一的日志和指标
备份：集中备份策略

总结

自托管 Windmill 以云托管成本的一小部分提供企业级工作流自动化。成功的关键是理解 PostgreSQL 身份验证要求，并使用纯十六进制密码来避免可能导致安装失败的特殊字符问题。

此设置的关键优势

经济高效：与云解决方案相比年省数百美元
生产就绪：可靠处理企业级工作负载
安全：HTTPS、隔离网络和资源限制
可扩展：可根据需要轻松添加 Worker 和资源
私密：您的代码和数据永远不会离开您的基础设施

此配置已在生产环境中经过测试，提供了业务关键工作流自动化所需的可靠性。故障排查步骤解决了部署过程中遇到的实际问题，特别是影响许多自托管安装的 PostgreSQL 身份验证问题。

对于复杂的工作流需求或企业部署，建议咨询专业人士以优化您的具体使用场景并确保最佳资源分配。

下一步

探索适用于 Windmill 的 Webhook 故障排查技术
查看处理大型数据集的负载优化
考虑与现有 n8n 安装的集成

关于 tva

tva 提供数据库系统、云环境和全球供应链的综合基础设施管理。我们系统化的方法将严格的安全协议与性能优化相结合，同时战略咨询服务实现数字能力和实物资产的精准协调——在所有业务中保持最高标准的卓越运营和合规水平。

访问 tva.sg 了解更多关于我们服务和其他自动化教程的信息。