创建应用程序

使用 bench 命令行工具创建一个 Frappe 应用脚手架。

创建应用

在开始之前,请确保你位于 bench 目录中。要确认这一点,请运行 bench find .

$ bench find .
/home/frappe/frappe-bench is a bench directory!

要创建我们的图书馆管理应用,请运行 new-app 命令:

bench new-app library_management

你会看到一些提示和类似下面的输出。你可以手动输入信息,或者直接按回车选择默认值。

App Title (default: Library Management):
App Description: Library Management System
App Publisher: Faris Ansari
App Email: [email protected]
App Icon (default 'octicon octicon-file-directory'):
App Color (default 'grey'):
App License (default 'MIT'):
'library_management' created at /home/frappe/frappe-bench/apps/library_management

Installing library_management
$ ./env/bin/pip install -q -U -e ./apps/library_management
$ bench build --app library_management
yarn run v1.22.4
$ FRAPPE_ENV=production node rollup/build.js --app library_management
Production mode
✔ Built js/moment-bundle.min.js
✔ Built js/libs.min.js
✨  Done in 1.95s.

系统会提示你填写应用的相关信息,填写完成后,一个名为 library_management 的应用将在 apps 文件夹中创建。

要查看 octicons 图标库中所有支持的图标完整列表,请访问 https://primer.style/octicons/

应用目录结构

你的应用目录结构应该类似于这样:

apps/library_management
├── README.md
├── library_management
│   ├── hooks.py
│   ├── library_management
│ │ └── __init__.py
│ ├── modules.txt
│ ├── patches.txt
│ ├── public
│ │ ├── css
│ │ └── js
│ ├── templates
│ │ ├── __init__.py
│ │ ├── includes
│ │ └── pages
│ │ └── __init__.py
│ └── www
└── pyproject.toml
  • library_management: 此目录将包含你应用的所有源代码

    • public: 存放静态文件,生产环境中将由 Nginx 提供这些文件
    • templates: 用于渲染 Web 视图的 Jinja 模板
    • www: 根据其目录路径提供服务的网页
    • library_management: 应用自带的默认模块
    • modules.txt: 应用中定义的模块列表
    • patches.txt: 用于数据库迁移的补丁条目
    • hooks.py: 用于扩展或拦截框架提供的标准功能的钩子
    • pyproject.toml: 指定应用的构建方式,你可以在此处可选地添加第三方 Python 依赖,这些依赖会在应用安装时被安装。

下一步:创建站点

安装与设置Bench

Bench 是用于管理 Frappe 应用和站点的命令行工具。

安装

如果你还没有安装 Bench,请按照安装指南进行操作。安装完成后,你应该能够运行以 bench 开头的命令。

运行以下命令来测试你的安装是否成功:

$ bench --version
5.1.0

创建 frappe-bench 目录

让我们创建项目文件夹,它将包含我们的应用和站点。运行以下命令:

$ bench init frappe-bench

这将在你当前的工作目录中创建一个名为 frappe-bench 的目录。它将执行以下操作:

  1. env 目录下创建一个 Python 虚拟环境。
  2. 获取并安装 frappe 应用作为 Python 包。
  3. 安装 frappe 的 node 模块。
  4. 构建静态资源。

目录结构

.
├── Procfile
├── apps
│   └── frappe
├── config
│   ├── pids
│   ├── redis_cache.conf
│   ├── redis_queue.conf
│   └── redis_socketio.conf
├── env
│   ├── bin
│   ├── include
│   ├── lib
│   └── share
├── logs
│   ├── backup.log
│   └── bench.log
└── sites
    ├── apps.txt
    ├── assets
    └── common_site_config.json
  • env:Python 虚拟环境

  • config:Redis 和 Nginx 的配置文件

  • logs:每个进程(Web、Worker)的日志文件

  • sites: 站点目录

    • assets: 生产环境中通过 Nginx 提供的静态资源
    • apps.txt: 已安装的 Frappe 应用列表
    • common_site_config.json: 所有站点通用的站点配置
  • apps: 应用目录

    • frappe: Frappe 应用目录
  • Procfile: 开发环境中运行的进程列表

启动 Bench 服务器

现在我们已经创建了 frappe-bench 目录,可以通过运行以下命令来启动 Frappe Web 服务器:

$ cd frappe-bench
$ bench start
18:16:36 system | redis_cache.1 started (pid=11231)
18:16:36 system | redis_socketio.1 started (pid=11233)
18:16:36 system | redis_queue.1 started (pid=11234)
18:16:36 system | socketio.1 started (pid=11236)
18:16:36 system | web.1 started (pid=11237)
18:16:36 system | watch.1 started (pid=11240)
18:16:36 system | schedule.1 started (pid=11241)
18:16:36 system | worker_short.1 started (pid=11242)
18:16:36 redis_queue.1 | 11234:C 10 Jul 2020 18:16:36.320 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
18:16:36 redis_queue.1 | 11234:C 10 Jul 2020 18:16:36.320 # Redis version=6.0.5, bits=64, commit=00000000, modified=0, pid=11234, just started
18:16:36 redis_queue.1 | 11234:C 10 Jul 2020 18:16:36.320 # Configuration loaded
18:16:36 system | worker_long.1 started (pid=11244)
18:16:36 redis_cache.1 | 11231:C 10 Jul 2020 18:16:36.318 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
18:16:36 redis_cache.1 | 11231:C 10 Jul 2020 18:16:36.318 # Redis version=6.0.5, bits=64, commit=00000000, modified=0, pid=11231, just started
18:16:36 redis_cache.1 | 11231:C 10 Jul 2020 18:16:36.318 # Configuration loaded
18:16:36 redis_cache.1 | 11231:M 10 Jul 2020 18:16:36.320 * Increased maximum number of open files to 10032 (it was originally set to 256).
18:16:36 redis_queue.1 | 11234:M 10 Jul 2020 18:16:36.325 * Increased maximum number of open files to 10032 (it was originally set to 256).
18:16:36 system | worker_default.1 started (pid=11245)
18:16:36 redis_cache.1 | 11231:M 10 Jul 2020 18:16:36.337 * Running mode=standalone, port=13000.
18:16:36 redis_cache.1 | 11231:M 10 Jul 2020 18:16:36.337 # Server initialized
18:16:36 redis_cache.1 | 11231:M 10 Jul 2020 18:16:36.337 * Ready to accept connections
18:16:36 redis_queue.1 | 11234:M 10 Jul 2020 18:16:36.367 * Running mode=standalone, port=11000.
18:16:36 redis_queue.1 | 11234:M 10 Jul 2020 18:16:36.367 # Server initialized
18:16:36 redis_queue.1 | 11234:M 10 Jul 2020 18:16:36.367 * Ready to accept connections
18:16:36 redis_socketio.1 | 11233:C 10 Jul 2020 18:16:36.359 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
18:16:36 redis_socketio.1 | 11233:C 10 Jul 2020 18:16:36.359 # Redis version=6.0.5, bits=64, commit=00000000, modified=0, pid=11233, just started
18:16:36 redis_socketio.1 | 11233:C 10 Jul 2020 18:16:36.359 # Configuration loaded
18:16:36 redis_socketio.1 | 11233:M 10 Jul 2020 18:16:36.374 * Increased maximum number of open files to 10032 (it was originally set to 256).
18:16:36 redis_socketio.1 | 11233:M 10 Jul 2020 18:16:36.417 * Running mode=standalone, port=12000.
18:16:36 redis_socketio.1 | 11233:M 10 Jul 2020 18:16:36.418 # Server initialized
18:16:36 redis_socketio.1 | 11233:M 10 Jul 2020 18:16:36.418 * Ready to accept connections
18:16:37 socketio.1 | listening on *: 9000
18:16:41 web.1 | * Running on http://0.0.0.0:8000/ (Press CTRL+C to quit)
18:16:41 web.1 | * Restarting with fsevents reloader
18:16:41 watch.1 | yarn run v1.22.4
18:16:41 watch.1 | $ node rollup/watch.js
18:16:42 watch.1 |
18:16:42 watch.1 | Rollup Watcher Started
18:16:42 watch.1 |
18:16:42 watch.1 | Watching...
18:16:42 web.1 | * Debugger is active!
18:16:42 web.1 | * Debugger PIN: 100-672-925
18:16:43 watch.1 | Rebuilding frappe-web-b4.css
18:16:44 watch.1 | Rebuilding frappe-chat-web.css
18:16:44 watch.1 | Rebuilding chat.js
18:16:45 watch.1 | Rebuilding frappe-recorder.min.js
18:16:48 watch.1 | Rebuilding checkout.min.js
18:16:48 watch.1 | Rebuilding frappe-web.min.js
18:16:51 watch.1 | Rebuilding bootstrap-4-web.min.js
18:16:52 watch.1 | Rebuilding control.min.js
18:16:54 watch.1 | Rebuilding dialog.min.js
18:16:57 watch.1 | Rebuilding desk.min.css
18:16:57 watch.1 | Rebuilding frappe-rtl.css
18:16:58 watch.1 | Rebuilding printview.css
18:16:58 watch.1 | Rebuilding desk.min.js
18:17:04 watch.1 | Rebuilding form.min.css
18:17:04 watch.1 | Rebuilding form.min.js
18:17:07 watch.1 | Rebuilding list.min.css
18:17:07 watch.1 | Rebuilding list.min.js
18:17:09 watch.1 | Rebuilding report.min.css
18:17:09 watch.1 | Rebuilding report.min.js
18:17:12 watch.1 | Rebuilding web_form.min.js
18:17:12 watch.1 | Rebuilding web_form.css
18:17:13 watch.1 | Rebuilding email.css
18:17:13 watch.1 | Rebuilding social.min.js
18:17:13 watch.1 | Rebuilding barcode_scanner.min.js
18:17:15 watch.1 | Rebuilding data_import_tools.min.js

这将启动多个进程,包括基于 Gunicorn 的 Python Web 服务器、用于缓存、任务队列和 SocketIO 发布/订阅的 Redis 服务器、后台 Worker、用于 SocketIO 的 Node 服务器以及用于编译 JS/CSS 文件的 Node 服务器。

Web 服务器将在端口 8000 上开始监听,但目前我们还没有任何站点可供服务。下一步是创建我们的应用,并创建一个安装了该应用的站点。

请确保不要关闭运行 bench start 的终端。要运行 bench 命令,请打开另一个终端,并 cd 到 frappe-bench 目录中。

到目前为止,你做得很好!

下一步:创建应用

安装

系统要求

本指南假设您使用的是个人电脑、VPS 或裸机服务器。您还需要使用 *nix 系统,因此支持任何 Linux 发行版和 macOS。如果您是 Windows 用户,可以在 WSL 中使用 Ubuntu。我们仅正式支持以下发行版。

  1. macOS
  2. Debian / Ubuntu

在此处了解更多关于架构的信息。

前置要求

依赖项 Frappe v14/v15 Frappe v16/develop
MariaDB 10.6.6+ 11.8
Python 3.10+ 3.14
NodeJS 18+ 24
Redis / valkey 6 6+
Yarn 1.12+ 1.22+
pip 20+ 25.3+
  • wkhtmltopdf:0.12.6 版本,带有修补过的 qt – 用于生成 PDF
  • cron:bench 的定时任务 – 自动证书续期、定时备份

macOS

安装 Xcode 工具的命令行版本。

xcode-select --install

安装 Homebrew。它可以让您在 macOS 上轻松安装软件包。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

(它可能会在最后提示您运行一些额外的命令,这将确保 brew 在您的 PATH 中可用)

安装 wkhtmltopdf

curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-2/wkhtmltox-0.12.6-2.macos-cocoa.pkg -O

installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target ~

现在,您可以通过运行以下命令轻松安装所需的软件包

brew install git redis [email protected] pkg-config mariadb-connector-c

如果您计划使用 PostgreSQL 而不是 MariaDB,那么您可以包含 postgresql

在此安装过程中,系统会提示您设置 MySQL root 密码。如果没有提示,您需要自行初始化 MySQL 服务器设置。您可以通过运行以下命令来完成:

sudo mariadb-secure-installation

请记住:仅在设置过程中未提示您输入密码时才运行此命令。

然后,继续执行通用步骤

Debian / Ubuntu

您应该运行 Debian 13+ 或 Ubuntu 24.04+,否则某些软件包可能会出现问题。

更新您系统的软件包索引

sudo apt update

安装 gitredismariadb

sudo apt install git redis-server libmariadb-dev mariadb-server mariadb-client pkg-config

在此安装过程中,系统会提示您设置 MySQL root 密码。如果没有提示,您需要自行初始化 MySQL 服务器设置。您可以通过运行以下命令来完成:

sudo mariadb-secure-installation

请记住:仅在设置过程中未提示您输入密码时才运行此命令。

请务必记住此密码,因为稍后会用到它。

安装 wkhtmltopdf

sudo apt install xvfb libfontconfig

从 https://wkhtmltopdf.org/downloads.html 下载并安装 wkhtmltopdf 软件包,然后运行此命令来安装该软件包。

sudo dpkg -i wkhtmltox_file.deb

通用依赖项

安装 nvm、node 和 yarn

我们建议使用 nvm 安装 node

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

nvm 安装完成后,您可能需要关闭终端并打开另一个标签页/窗口,或者 source 您的 shell 的 rc 文件(例如:~/.bashrc~/.zshrc。然后运行以下命令来安装 node。

nvm install 24

通过运行以下命令验证已安装的版本:

$ node -v
v24.12.0

最后,使用 npm 安装 yarn

npm install -g yarn

** 安装 uv 和 python **

我们建议使用 uv 来管理 python

curl -LsSf https://astral.sh/uv/install.sh | sh

uv 安装完成后,您可能需要关闭终端并打开另一个标签页/窗口,或者 source 您的 shell 的 rc 文件(例如:~/.bashrc~/.zshrc。然后运行以下命令来安装 python。

uv python install 3.14 --default

或者,对于版本 15,您可以选择 3.10-3.13 之间的版本。

安装 Bench CLI

通过 pip 安装 bench

uv tool install frappe-bench

通过检查版本来确认 bench 安装成功

bench --version

创建您的第一个 bench。

mkdir ~/frappe
cd ~/frappe
bench init my-bench

恭喜,您已在系统上成功安装了 bench。

先决条件

以下资源列表可帮助您开始使用 Frappe 构建应用程序。

1. Python

Frappe 使用 Python 3 进行服务器端编程。强烈建议您在开始使用 Frappe 框架构建应用程序之前,先学习 Python。

资源:

  1. Codecademy Python 教程
  2. Python 官方教程

2. MariaDB / Postgres

要使用 Frappe 创建数据库驱动的应用程序,您必须了解数据库管理和常见 SQL 查询的基础知识。

资源:

  1. Codecademy SQL 教程
  2. DigitalOcean 提供的 MySQL 基础教程
  3. MariaDB 入门指南

3. HTML / CSS

如果您想使用 Frappe 框架构建用户界面,您需要学习基本的 HTML / CSS 以及 Bootstrap CSS 框架。

资源:

  1. Codecademy HTML/CSS 教程
  2. Bootstrap 入门指南

4. JavaScript / jQuery

要自定义表单并创建交互式用户界面,您必须学习 JavaScript 和 jQuery 库。

资源:

  1. 现代 JavaScript 教程
  2. Codecademy JavaScript 教程
  3. Codecademy jQuery 教程

5. Jinja 模板

要构建 Web 视图和打印模板,您需要学习 Jinja 模板语言。

资源:

  1. Jinja 文档

6. Git / GitHub

学习如何使用 Git 和 GitHub 为开源项目做贡献,这两个强大的工具可以帮助您管理代码并与他人分享。

资源:

  1. Git 基础教程
  2. 如何为开源项目做贡献

如果您对这些工具的基础知识已经熟悉,那么您就可以开始使用 Frappe 框架构建应用程序了。

下一步:创建 Bench

介绍

什么是 Frappe 框架?

Frappe,发音为 fra-pay,是一个全栈、开箱即用的 Web 框架,使用 Python 和 Javascript 编写,并以 MariaDB 作为数据库。它是驱动 ERPNext 的框架,非常通用,可用于构建数据库驱动的应用程序。

为什么选择 Frappe?

Frappe 与其他框架的关键区别在于,元数据也被视为数据。这使得您可以非常轻松地构建前端。我们信奉单体架构,因此 Frappe 几乎包含了构建现代 Web 应用程序所需的一切。它拥有一个功能齐全的管理界面,称为 Desk,可处理表单、导航、列表、菜单、权限、文件附件等众多功能,开箱即用。在此处了解更多信息。

主要特性

  1. 全栈框架:Frappe 涵盖前端和后端开发,允许开发人员使用单一框架构建完整的应用程序。
  2. 内置管理界面:提供预构建、可自定义的管理仪表板,用于管理应用程序数据,减少开发时间和精力。
  3. 基于角色的权限:全面的用户和角色管理系统,用于控制应用程序内的访问和权限。
  4. REST API:为所有模型自动生成 RESTful API,便于与其他系统和服务的集成。
  5. 可自定义的表单和视图:使用服务器端脚本和客户端 JavaScript 进行灵活的表单和视图自定义。
  6. 报表生成器:强大的报表工具,允许用户无需编写任何代码即可创建自定义报表。

安装

在您使用 Frappe 之前,需要先进行安装。我们提供了一份完整的安装指南,涵盖了所有可能性,本指南还将帮助您了解后端技术栈。

学习与社区

  1. Frappe School – 通过维护者或社区提供的各种课程学习 Frappe 框架和 ERPNext
  2. GitHub – 探索源代码、贡献代码,并与 Frappe 社区协作。
  3. 讨论论坛 – 在我们的论坛上与我们不断壮大的社区交流,提问、帮助他人并成为社区的一员。
  4. buildwithhussain.com – 观看 Frappe 框架在实际应用中构建世界级 Web 应用程序的案例。