frappe-ops-deployment

生产部署

使用传统方式（bench + Nginx + Supervisor）或 Docker（frappe_docker + Compose）将 Frappe/ERPNext 部署到生产环境。Frappe 官方建议新部署使用 Docker。

快速参考

# Traditional production setup (one command)
sudo bench setup production [frappe-user]

# What it configures:
# 1. Supervisor — process management (gunicorn, workers, Redis, socketio)
# 2. Nginx — reverse proxy, static files, websocket proxy
# 3. Sudoers — allows frappe-user to restart services

# Individual setup commands
bench setup supervisor          # Generate supervisor config
bench setup nginx               # Generate nginx config
bench setup sudoers $(whoami)   # Allow service restarts without password

# Symlink configs into system directories
sudo ln -s $(pwd)/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
sudo ln -s $(pwd)/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf

# SSL setup
sudo -H bench setup lets-encrypt [site-name]
sudo -H bench setup lets-encrypt [site-name] --custom-domain [domain]

# DNS multitenancy (multiple sites on port 80/443)
bench config dns_multitenant on
bench setup nginx
sudo service nginx reload

---

部署决策树

Which deployment method?
|
+-- New server, minimal ops experience?
|   +-- Docker (frappe_docker) — recommended by Frappe
|
+-- Existing server with bench already installed?
|   +-- Traditional (bench setup production)
|
+-- Need custom Frappe apps or complex build?
|   +-- Docker with custom image build
|
+-- Cloud hosting (AWS/GCP/Azure)?
|   +-- Docker on VM or Kubernetes
|   +-- OR Frappe Cloud (managed)
|
+-- Single site or multi-site?
|   +-- Single site: standard setup
|   +-- Multi-site: DNS multitenancy required

---

传统部署

进程架构

Internet → Nginx (port 80/443)
               |
               +-- Static files served directly
               +-- /api, /app → Gunicorn (port 8000)
               +-- /socket.io → Node.js socketio (port 9000)

Supervisor manages:
  - frappe-bench-web (gunicorn)
  - frappe-bench-socketio (node)
  - frappe-bench-worker-short
  - frappe-bench-worker-default
  - frappe-bench-worker-long
  - frappe-bench-redis-cache
  - frappe-bench-redis-queue
  - frappe-bench-schedule (scheduler)

分步设置

# 1. Install bench (as non-root user)
sudo pip3 install frappe-bench
bench init frappe-bench --frappe-branch version-15
cd frappe-bench

# 2. Create site
bench new-site mysite.example.com
bench --site mysite.example.com install-app erpnext

# 3. Production setup (configures nginx + supervisor + sudoers)
sudo bench setup production $(whoami)

# 4. Verify processes are running
sudo supervisorctl status

# 5. Verify nginx config
sudo nginx -t && sudo systemctl reload nginx

Nginx 配置

bench setup nginx 会生成 config/nginx.conf，其中包含：

• 每个站点一个服务器块（DNS 多租户）
• 代理到端口 8000 上的 gunicorn
• WebSocket 代理到端口 9000 上的 socketio
• 从 sites/ 目录提供静态文件
• 客户端最大请求体大小（默认值因版本而异）

务必禁用默认 nginx 站点，以避免端口 80 冲突：

sudo rm /etc/nginx/sites-enabled/default
# OR disable: sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak

Supervisor 配置

bench setup supervisor 会生成 config/supervisor.conf，其中包含：

• --skip-redis 标志，用于在由外部管理 Redis 时跳过 Redis

对于 CentOS/RHEL：Supervisor 配置使用 .ini 扩展名而不是 .conf。

---

SSL / HTTPS

Let's Encrypt（推荐）

# Automated setup with cron renewal
sudo -H bench setup lets-encrypt mysite.example.com

# For custom domain (site name differs from domain)
sudo -H bench setup lets-encrypt mysite.example.com --custom-domain www.example.com

# Manual renewal
sudo bench renew-lets-encrypt

前提条件：

• 已启用 DNS 多租户（bench config dns_multitenant on）
• 域名解析到服务器 IP
• 为 ACME 挑战开放端口 80
• 拥有 root/sudo 访问权限

证书位置：/etc/letsencrypt/live/example.com/

• fullchain.pem — 证书 + 证书链
• privkey.pem — 私钥

证书每 90 天过期一次。设置命令会添加每月运行的 cron 任务以续期。

自定义 SSL 证书

# 1. Place certificate files
sudo mkdir -p /etc/nginx/conf.d/ssl
sudo cp certificate.crt /etc/nginx/conf.d/ssl/
sudo cp private.key /etc/nginx/conf.d/ssl/
sudo chmod 600 /etc/nginx/conf.d/ssl/private.key

# 2. Configure site
bench set-config ssl_certificate "/etc/nginx/conf.d/ssl/certificate.crt"
bench set-config ssl_certificate_key "/etc/nginx/conf.d/ssl/private.key"

# 3. Regenerate and reload
bench setup nginx
sudo systemctl reload nginx

配置 SSL 后，所有 HTTP 流量都会自动重定向到 HTTPS。

---

DNS 多租户（多站点）

# Enable DNS-based site routing
bench config dns_multitenant on

# Create sites with domain names
bench new-site site1.example.com
bench new-site site2.example.com

# Regenerate nginx (creates server blocks per site)
bench setup nginx
sudo systemctl reload nginx

务必使用实际域名作为站点名称。Nginx 会根据 Host 标头将请求路由到正确的站点。

---

Docker 部署

架构（frappe_docker）

Docker Compose Services:
  - configurator  — initializes DB/Redis config (runs once)
  - backend       — Frappe/ERPNext application server (gunicorn)
  - frontend      — Nginx reverse proxy
  - websocket     — Node.js Socket.IO server
  - queue-short   — RQ worker for short jobs
  - queue-long    — RQ worker for long jobs
  - (external)    — MariaDB/PostgreSQL + Redis (separate containers or managed)

Shared Volume:
  - sites:/home/frappe/frappe-bench/sites (persistent data)

生产环境 Docker Compose

# Clone frappe_docker
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# Use compose.yaml for production
# Key environment variables:
#   DB_HOST, DB_PORT — database connection
#   REDIS_CACHE, REDIS_QUEUE — Redis endpoints
#   FRAPPE_SITE_NAME_HEADER — for multi-site routing
#   PROXY_READ_TIMEOUT — upstream timeout
#   CLIENT_MAX_BODY_SIZE — upload limit (default 50m)

docker compose -f compose.yaml up -d

自定义镜像构建

# Build custom image with your apps
export APPS_JSON='[
  {"url":"https://github.com/frappe/erpnext","branch":"version-15"},
  {"url":"https://github.com/your-org/custom-app","branch":"main"}
]'

docker build \
  --build-arg APPS_JSON_BASE64=$(echo $APPS_JSON | base64 -w 0) \
  --tag your-registry/custom-erpnext:latest \
  images/custom/

---

安全加固

防火墙（UFW）

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# NEVER expose ports 8000, 9000, 6379, 3306 to the internet

Fail2Ban

sudo apt install fail2ban
sudo systemctl enable fail2ban

# /etc/fail2ban/jail.local
# [sshd]
# enabled = true
# maxretry = 5
# bantime = 3600

Redis 身份验证

# Secure Redis for multi-bench environments
bench create-rq-users --set-admin-password
# Generates unique passwords per bench for Redis auth

其他加固措施

• 务必禁用 root SSH 登录（在 /etc/ssh/sshd_config 中设置 PermitRootLogin no）
• 务必使用 SSH 密钥身份验证，并禁用密码身份验证
• 切勿以 root 身份运行 bench——创建专用的 frappe 用户
• 务必保持系统软件包更新（sudo apt update && sudo apt upgrade）
• 务必在 site_config.json 中将 ALLOW_CORS 仅设为可信域名

---

零停机更新

# Traditional deployment
bench update --pull --patch --build --requirements
# Supervisor auto-restarts workers after update

# Docker deployment
# 1. Pull new image
docker compose pull
# 2. Recreate containers (rolling)
docker compose up -d --no-deps backend websocket queue-short queue-long
# 3. Run migrations
docker compose exec backend bench --site mysite.example.com migrate

---

版本差异

功能	v14	v15	v16
推荐使用 Docker	否	官方推荐	是
create-rq-users	否	是	是
ARM64 Docker 镜像	否	是	是
站点级日志	v13+	是	是
extend_doctype_class	否	否	是

---

参考文件

文件	内容
examples.md	完整的部署脚本和配置
anti-patterns.md	常见部署错误
workflows.md	分步部署工作流

相关技能

• frappe-ops-backup — 备份与灾难恢复
• frappe-ops-performance — 性能调优
• frappe-ops-bench — Bench CLI 参考
• frappe-ops-upgrades — 版本升级流程