ERPNext 完全指南 2026：开源 ERP 安装、配置、二次开发实战

┌─────────────────────────────────────┐
│         ERPNext (应用层)              │
│  财务 | CRM | 销售 | 采购 | 库存 | HR  │
├─────────────────────────────────────┤
│       Frappe Framework (框架层)       │
│  DocType | REST API | 权限 | 工作流    │
├─────────────────────────────────────┤
│  Python (后端) | MariaDB (数据库)     │
│  JavaScript/Vue (前端) | Redis (缓存) │
└─────────────────────────────────────┘

# 1. 安装 Docker 和 Docker Compose
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

# 2. 安装 Docker Compose（如果未自带）
sudo apt install docker-compose-plugin

# 3. 克隆官方 docker-compose 配置
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# 4. 创建环境变量文件
cp example.env .env

# 编辑 .env 文件，设置以下关键参数：
# SITE_NAME=erp.yourdomain.com
# DB_ROOT_USER=root
# DB_ROOT_PASSWORD=your_secure_password
# ADMIN_PASSWORD=your_admin_password

# 5. 启动服务
docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml \
  config > ~/docker-compose.yml

docker compose -f ~/docker-compose.yml up -d

# 6. 创建新站点
docker compose -f ~/docker-compose.yml exec backend \
  bench new-site erp.yourdomain.com \
  --mariadb-root-password your_secure_password \
  --admin-password your_admin_password \
  --install-app erpnext

# 7. 访问 ERPNext
# 浏览器打开 http://your-server-ip:8080
# 默认管理员账号：Administrator
# 密码：你在 .env 中设置的 ADMIN_PASSWORD

# 使用 Let's Encrypt 获取免费 SSL 证书
docker compose -f ~/docker-compose.yml exec backend \
  bench setup nginx

# 或使用 Traefik 自动管理 HTTPS
docker compose -f compose.yaml \
  -f overrides/compose.traefik.yaml \
  config > ~/docker-compose-traefik.yml

docker compose -f ~/docker-compose-traefik.yml up -d

# 1. 安装依赖
sudo apt update
sudo apt install python3-dev python3-setuptools python3-pip \
  python3-distutils python3.10-venv software-properties-common \
  mariadb-server mariadb-client redis-server nodejs npm \
  yarn cron xvfb libfontconfig wkhtmltopdf

# 2. 配置 MariaDB
sudo mysql -u root -e "
  CREATE DATABASE erpnext;
  CREATE USER 'erpnext'@'localhost' IDENTIFIED BY 'your_password';
  GRANT ALL PRIVILEGES ON erpnext.* TO 'erpnext'@'localhost';
  FLUSH PRIVILEGES;
"

# 3. 安装 bench（Frappe 的 CLI 工具）
pip3 install frappe-bench

# 4. 初始化 bench
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench

# 5. 创建新站点
bench new-site erp.yourdomain.com \
  --db-name erpnext \
  --db-password your_password \
  --admin-password your_admin_password

# 6. 安装 ERPNext 应用
bench get-app --branch version-15 erpnext
bench --site erp.yourdomain.com install-app erpnext

# 7. 启动开发服务器
bench start
# 访问 http://localhost:8000

# 多公司架构
如果你的集团有多个子公司，可以添加多家公司，
ERPNext 支持公司间的交易和合并报表。

管理员（System Manager）→ 所有权限
会计（Accounts Manager）→ 财务模块
销售（Sales Manager）→ 销售模块
仓库（Stock Manager）→ 库存模块
HR（HR Manager）→ 人力资源模块

# 通过 Frappe API 创建用户（Python 脚本）
import frappe

user = frappe.get_doc({
    "doctype": "User",
    "email": "zhangsan@company.com",
    "first_name": "张三",
    "roles": [{"role": "Sales Manager"}]
})
user.insert()

资产（Assets）
├── 流动资产
│   ├── 现金及银行存款
│   ├── 应收账款
│   └── 存货
├── 固定资产
│   ├── 房屋建筑
│   └── 设备
负债（Liabilities）
├── 流动负债
│   ├── 应付账款
│   └── 短期借款
权益（Equity）
├── 实收资本
└── 未分配利润
收入（Income）
├── 主营业务收入
└── 其他业务收入
费用（Expenses）
├── 主营业务成本
├── 销售费用
├── 管理费用
└── 财务费用

# 销售发票的自动分录
借：应收账款         ¥10,000
    贷：主营业务收入     ¥8,849.56
        应交税费-销项税  ¥1,150.44

# 采购入库的自动分录
借：库存商品         ¥5,000
    贷：应付账款         ¥5,000

总部仓库
├── A 区 - 原材料
│   ├── A-01 电子元器件
│   └── A-02 结构件
├── B 区 - 成品
│   ├── B-01 待发货
│   └── B-02 已检验
└── C 区 - 退货

# 通过 Frappe 脚本设置库存预警
frappe.db.set_value("Item", "ITEM-001", "re_order_level", 100)
frappe.db.set_value("Item", "ITEM-001", "warehouse", "总部仓库")

线索（Lead）
  ↓
商机（Opportunity）
  ↓
报价单（Quotation）
  ↓
销售订单（Sales Order）
  ↓
发货单（Delivery Note）
  ↓
销售发票（Sales Invoice）
  ↓
收款（Payment Entry）

# 考勤规则配置
attendance_policy = {
    "working_hours": "09:00-18:00",
    "late_entry_threshold": 15,  # 分钟
    "early_exit_threshold": 15,
    "holiday_list": "2026-法定节假日"
}

# 请假类型
leave_types = [
    {"name": "年假", "max_leaves": 10},
    {"name": "病假", "max_leaves": 5},
    {"name": "事假", "max_leaves": 0},  # 需审批
    {"name": "婚假", "max_leaves": 3},
]

产品：智能音箱 V2.0
├── 主板组件 (x1)
│   ├── 主控芯片 (x1)
│   ├── 内存模块 (x2)
│   └── WiFi 模块 (x1)
├── 音频组件 (x1)
│   ├── 扬声器 (x2)
│   └── 功放板 (x1)
├── 外壳 (x1)
└── 电源适配器 (x1)

生产计划（Production Plan）
  ↓
工单（Work Order）
  ↓
领料（Material Transfer）
  ↓
生产（Manufacture）
  ↓
质检（Quality Inspection）
  ↓
入库（Stock Entry）

# 1. 创建开发站点
bench new-site dev.localhost --force
bench use dev.localhost

# 2. 创建自定义应用
bench new-app my_custom_app

# 目录结构：
# my_custom_app/
# ├── my_custom_app/
# │   ├── __init__.py
# │   ├── hooks.py          # 应用钩子配置
# │   ├── modules.txt        # 模块列表
# │   ├── custom_doctype/    # 自定义文档类型
# │   └── api.py             # 自定义 API
# └── setup.py

# 通过 Python 代码定义 DocType
import frappe
from frappe.model.document import Document

class ProjectTask(Document):
    pass

# hooks.py 中注册
# doc_events = {
#     "Project Task": {
#         "on_update": "my_custom_app.tasks.notify_assignee"
#     }
# }

# my_custom_app/api.py
import frappe
from frappe import _

@frappe.whitelist()
def get_project_summary(project_name):
    """获取项目摘要信息"""
    project = frappe.get_doc("Project", project_name)

    tasks = frappe.get_all("Project Task",
        filters={"project": project_name},
        fields=["task_name", "status", "assigned_to", "deadline"]
    )

    return {
        "project_name": project.project_name,
        "status": project.status,
        "budget": project.budget,
        "tasks": tasks,
        "completion": project.percentage_complete
    }

# 调用方式：
# GET /api/method/my_custom_app.api.get_project_summary?project_name=PRJ-001

# 定义采购审批工作流
workflow = {
    "workflow_name": "Purchase Approval",
    "document_type": "Purchase Order",
    "states": [
        {"state": "Draft", "allow_edit": "Purchase Manager"},
        {"state": "Pending Approval", "allow_edit": "Purchase Manager"},
        {"state": "Approved", "allow_edit": "Director"},
        {"state": "Rejected", "allow_edit": "Director"},
    ],
    "transitions": [
        {"from": "Draft", "to": "Pending Approval", "action": "Submit", "allowed": "Purchase Manager"},
        {"from": "Pending Approval", "to": "Approved", "action": "Approve", "allowed": "Director"},
        {"from": "Pending Approval", "to": "Rejected", "action": "Reject", "allowed": "Director"},
    ]
}

# my_custom_app/reports/sales_summary.py
import frappe

def execute(filters=None):
    columns = [
        {"fieldname": "customer", "label": "客户", "fieldtype": "Link", "options": "Customer", "width": 200},
        {"fieldname": "total_sales", "label": "销售额", "fieldtype": "Currency", "width": 150},
        {"fieldname": "total_qty", "label": "数量", "fieldtype": "Int", "width": 100},
    ]

    conditions = ""
    if filters.get("from_date"):
        conditions += f" AND si.posting_date >= '{filters.from_date}'"
    if filters.get("to_date"):
        conditions += f" AND si.posting_date <= '{filters.to_date}'"

    data = frappe.db.sql(f"""
        SELECT
            si.customer,
            SUM(si.grand_total) as total_sales,
            SUM(si.total_qty) as total_qty
        FROM `tabSales Invoice` si
        WHERE si.docstatus = 1 {conditions}
        GROUP BY si.customer
        ORDER BY total_sales DESC
    """, as_dict=True)

    return columns, data

// 自定义表单脚本
frappe.ui.form.on('Sales Order', {
    refresh: function(frm) {
        // 添加自定义按钮
        frm.add_custom_button('导出 PDF', function() {
            frappe.call({
                method: 'my_custom_app.api.export_pdf',
                args: { docname: frm.doc.name },
                callback: function(r) {
                    window.open(r.message.url);
                }
            });
        });
    },

    validate: function(frm) {
        // 自定义验证
        if (frm.doc.discount > 20) {
            frappe.throw('折扣不能超过 20%');
        }
    }
});

# 备份站点
bench --site erp.yourdomain.com backup

# 备份到云端
bench --site erp.yourdomain.com backup --with-files

# 恢复备份
bench --site erp.yourdomain.com restore /path/to/database.sql.gz

# 定时备份（添加到 crontab）
0 2 * * * cd /home/frappe/frappe-bench && bench backup-all-sites

# 1. 启用 Redis 缓存（在 site_config.json 中）
{
    "cache_redis": "redis://localhost:6379"
}

# 2. 数据库索引优化
# 对高频查询字段添加索引
frappe.db.add_index("Sales Invoice", ["customer", "posting_date"])

# 3. 启用 Gunicorn 多进程
# 在 bench 配置中设置
bench config set-common-config -c gunicorn_workers 4

# 查看 bench 日志
bench --site erp.yourdomain.com logs

# 查看 MariaDB 慢查询
mysql -u root -e "SHOW VARIABLES LIKE 'slow_query_log%';"

# 监控服务器资源
htop
iotop

# ERPNext REST API 示例
import requests

# 获取客户列表
response = requests.get(
    "https://erp.yourdomain.com/api/resource/Customer",
    headers={"Authorization": "token api_key:api_secret"}
)
customers = response.json()

# 创建销售订单
response = requests.post(
    "https://erp.yourdomain.com/api/resource/Sales Order",
    headers={"Authorization": "token api_key:api_secret", "Content-Type": "application/json"},
    json={"customer": "CUST-001", "items": [{"item_code": "ITEM-001", "qty": 10}]}
)