n8n 工作流自动化 Self-Hosted Configuration Pitfalls

n8nself-hostedworkflow automationDockerPostgreSQL

Pitfall 1: N8N_WEBHOOK_URL Mismatch with Reverse Proxy

The most common n8n self-hosted pitfall: the URL n8n uses internally doesn't match how external callers reach it.

Symptoms:

Workflow manual trigger shows "success" but nothing actually runs
Webhook returns 200 but data never enters the queue
Logs show `Received webhook PENDING` with no follow-up processing

Root Cause:

n8n uses N8N_WEBHOOK_URL to tell external callers where to POST data. When N8N_WEBHOOK_URL=https://example.com/webhook, n8n tells callers "POST to https://example.com/webhook/xxx". If Nginx doesn't pass the Host header correctly or there's a certificate issue, the callback URL n8n generates is wrong.

Debugging:

# Check actual environment variables inside the n8n container
docker exec -it n8n_container_name printenv | grep -i web

# Check n8n logs (shows whether webhook URL is correct)
docker logs n8n_container_name 2>&1 | grep -i webhook

Correct Nginx reverse proxy config:

location /webhook/ {
    proxy_pass http://127.0.0.1:5678/webhook/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Critical: WebSocket support (n8n editor needs this)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

docker-compose.yml environment variables:

environment:
  - N8N_WEBHOOK_URL=https://your-domain.com/webhook
  - N8N_PROTOCOL=https
  - WEBHOOK_URL=https://your-domain.com/webhook

---

Pitfall 2: N8N_HOST Breaks the Editor

This usually appears after upgrading to n8n v1.x. The editor page shows blank, or clicking any node does nothing.

Root Cause:

N8N_HOST defaults to 0.0.0.0 (listen on all interfaces). But under certain Docker network configurations, n8n's internal Host header gets set to the container's internal IP (e.g., 172.17.0.2). When you browse to https://example.com, n8n generates static asset URLs pointing to https://172.17.0.2:5678/..., so your browser can't load the JS.

How to confirm:

Open Chrome DevTools → Network, find the Failed JS requests, check what the Request URL is. If the Host is a private IP, you confirmed it.

Two solutions:

Option A: Explicitly set N8N_HOST

environment:
  - N8N_HOST=your-domain.com
  - N8N_PORT=5678

Option B: If using Nginx with a sub-path

environment:
  - N8N_HOST=your-domain.com
  - N8N_BASE_URL=/n8n
  - WEBHOOK_URL=https://your-domain.com/n8n/webhook

Nginx config:

location /n8n/ {
    proxy_pass http://127.0.0.1:5678/n8n/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

---

Pitfall 3: PostgreSQL Connection Failures

After switching from SQLite to PostgreSQL, database connection issues are the most common problem.

Error messages (from docker logs):

ERROR: Unable to initialize database due to error: Password authentication failed for user "n8n"
or
ERROR: Cannot connect to database (connection timeout)

Debugging steps:

1. Confirm PostgreSQL container is running:

docker ps | grep postgres
docker logs postgres_container_name 2>&1 | tail -20

2. Test connection from inside the n8n container:

docker exec -it n8n_container_name psql -h postgres -U n8n -d n8n
# Enter the password from POSTGRES_PASSWORD in docker-compose.yml

3. Check docker-compose.yml database config:

services:
  n8n:
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_password_change_me
  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=n8n_password_change_me
      - POSTGRES_DB=n8n
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5

Key details:

`DB_POSTGRESDB_HOST` must be `postgres` (Docker service name), not `localhost` or `127.0.0.1`
Add `condition: service_healthy` to depends_on so n8n only starts after PostgreSQL is ready
Don't use special characters (like `$`) in PostgreSQL passwords — some versions parse them incorrectly

---

Checklist to Avoid These Pitfalls Next Time

After configuring, verify with this checklist:

# 1. Check n8n reads the correct WEBHOOK URL
docker exec -it n8n_container_name printenv | grep -E "(N8N_WEBHOOK|WEBHOOK|N8N_HOST)"

# 2. Trigger a test webhook (curl or Postman)
curl -X POST https://your-domain.com/webhook/test-uuid -H "Content-Type: application/json" -d '{"test": true}'

# 3. Check PostgreSQL health
docker exec -it postgres_container_name pg_isready -U n8n

# 4. Verify webhook registration (n8n logs)
docker logs n8n_container_name 2>&1 | grep "webhook"

# 5. Open editor in browser, verify static assets load correctly
# DevTools → Network, confirm n8n.abc123.js and similar files load

---

Summary

The three most common n8n self-hosted pitfalls:

1. **Webhook URL mismatch**: Always ensure N8N_WEBHOOK_URL matches the external access URL

2. **Editor static asset loading failure**: Explicitly set N8N_HOST to your domain name

3. **PostgreSQL connection**: Use Docker service name for DB_POSTGRESDB_HOST, add service_healthy dependency

For more complex workflow automation with n8n, check the official self-hosted guide first. If you're debugging similar issues on other self-hosted tools, the GitHub Actions troubleshooting guide shows how to read logs effectively.

👉 **Try MiniMax API**: n8n can call MiniMax API via its Webhook node to build AI-powered content moderation, data cleaning, and multilingual translation workflows. View plans