分类： 指南 – 部署

如何启用社交登录

使用 Facebook、Google 或 GitHub 身份验证登录 Frappe，您的用户将无需再记住另一个密码。

系统使用这些服务提供的电子邮件地址来匹配 Frappe 中的现有用户。如果未找到此类用户，且网站设置中未禁用注册功能，则会创建一个默认类型为“网站用户”的新用户。任何系统管理员之后都可以将用户类型从“网站用户”更改为“系统用户”，以便该用户可以访问桌面。

启用社交登录后的登录界面

要启用这些注册功能，您需要从这些身份验证服务中为您的 Frappe 站点获取客户端 ID 和客户端密钥。客户端 ID 和客户端密钥需在 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端 ID 和 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端密钥 中设置。以下是获取这些凭据的步骤。

如果您的站点启用了 HTTPS，请使用 https://{{ yoursite }}。

Frappe

这里假设您在 Frappe 框架上构建了两个站点。站点 A 是 https://sitea.com，站点 B 是 https://siteb.com。您希望使用 https://sitea.com 作为登录提供方，并在 https://siteb.com 上设置社交登录，以便通过 https://sitea.com 登录。

  1. 前往作为登录提供方的 https://sitea.com
  2. 转到 OAuth 客户端列表
  3. 创建新的 OAuth 客户端
  4. 输入应用程序名称（用于标识站点 B 的名称）
  5. 在“重定向 URI”和“默认重定向 URI”中输入 https://siteb.com/api/method/frappe.integrations.oauth2_logins.login_via_frappe
  6. 保存文档后，将生成应用程序客户端 ID 和应用程序客户端密钥
  7. 前往您要设置社交登录的 https://siteb.com
  8. 转到“社交登录密钥”并创建一个新密钥
  9. 输入在步骤 6 中获取的客户端 ID 和客户端密钥
  10. 选择“Frappe”作为社交登录提供方
  11. 输入 https://sitea.com 作为基础 URL，然后保存文档。

Facebook

  1. 前往 https://developers.facebook.com
  2. 点击（顶栏中的）“应用”> “新建应用”，并填写表单。
  3. 转到“设置”> “基本”，设置联系邮箱并保存更改。
  4. 转到“设置”> “高级”，找到有效的 OAuth 重定向 URI 字段，并输入：
    http://{{ yoursite }}/api/method/frappe.integrations.oauth2_logins.login_via_facebook
  5. 在“高级”选项卡中保存更改。
  6. 转到“状态和审核”，并开启“您是否希望将此应用及其所有实时功能提供给公众？”
  7. 转到“仪表盘”，点击“应用密钥”旁边的“显示”按钮，将应用 ID 和应用密钥复制到 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端 ID 和 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端密钥 中。

Google

  1. 前往 https://console.developers.google.com
  2. 创建一个新项目并填写表单。
  3. 点击“API 和服务”> “凭据”> “创建新的客户端 ID”
  4. 填写表单：
  • Web 应用程序
  • 已授权的 JavaScript 来源为 http://{{ yoursite }}
  • 已授权的重定向 URI 为
    http://{{ yoursite }}/api/method/frappe.integrations.oauth2_logins.login_via_google
  1. 转到“Web 应用程序的客户端 ID”部分，将客户端 ID 和客户端密钥复制到 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端 ID 中。

GitHub

  1. 前往 https://github.com/settings/applications
  2. 点击“注册新应用程序”
  3. 填写表单：
  • 主页 URL 为 http://{{ yoursite }}
  • 授权回调 URL 为
    http://{{ yoursite }}/api/method/frappe.integrations.oauth2_logins.login_via_github
  1. 点击“注册应用程序”。
  2. 将生成的客户端 ID 和客户端密钥复制到 桌面 > 网站 > 设置 > 社交登录密钥 和 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端密钥 中。

Office 365

  1. 前往 https://portal.azure.com
  2. 创建新的 Azure Active Directory > 应用注册。
  3. 点击“新建应用程序注册”
  4. 填写表单：
  • 应用程序名称
  • 选择“任何组织目录中的帐户（任何 Azure AD 目录 – 多租户）”。
  • 应用程序类型 – Web 应用 / API
  • 重定向 URI 为
  • 主页 URL 为 http://{{ yoursite }}
  • 授权回调 URL 为 http://{{ yoursite }}//api/method/frappe.integrations.oauth2_logins.login_via_office365
  1. 点击“注册应用程序”。
  2. 转到 Azure 门户中的“概述”部分，将应用程序（客户端）ID 复制到 **桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端 ID
  3. 转到 Azure 门户中的“证书和机密”部分，创建新的客户端机密，然后通过添加到 桌面 > 集成 > 身份验证 > 社交登录密钥 > 客户端密钥 来复制客户端机密。
  4. 选择“Office 365”作为社交登录提供方
  5. 点击“启用社交登录”并保存
  6. 转到“令牌配置”部分，点击“添加可选声明”
  • 添加令牌类型 > ID > 电子邮件

迁移

项目在其生命周期中经常会经历与数据库结构相关的变更。
有时也可能需要对现有数据进行修补。Frappe 内置了处理这些场景的工具。

当你从任何 Frappe 应用（包括 Frappe 本身）拉取更新时，应运行
bench migrate 来应用结构变更和数据迁移（如果有）。

结构变更

你可以编辑 DocType 来添加、删除或修改字段。保存 DocType 时，
包含 DocType 数据的 JSON 文件会被添加到应用的源代码树中。
当你将应用添加到站点时，DocType 会使用此 JSON 文件进行安装。
要进行结构变更，需要在配置中设置 developer_mode。

运行同步（bench migrate）时，系统中的 doctype 会根据应用中的 JSON 文件
同步到其最新版本。

注意：字段是软删除的，即列不会从数据库表中移除，
但它们将不会在文档中可见。这样做是为了避免任何潜在的数据丢失情况，
并允许你编写可能需要已删除字段值的数据迁移脚本。

注意：Frappe 不支持反向结构迁移。

数据迁移

在引入与数据相关的更改时，你可能希望运行一次性脚本来
修改现有数据，以符合新代码的预期。

要向代码中添加数据迁移，你需要编写一个 execute
函数到一个 Python 模块中，并将其添加到应用的 patches.txt 中。
或者，你可以使用以下命令以交互方式创建一个新的补丁：

$ bench create-patch
Select app for new patch (frappe, hrms, ecommerce_integrations, erpnext): frappe
Provide DocType name on which this patch will apply: User
Describe what this patch does: Improve Indexing
Provide filename for this patch [improve_indexing.py]:
Patch folder '/home/ankush/benches/develop/apps/frappe/frappe/core/doctype/user/patches' doesn't exist, create it? [Y/n]: y
Created /home/ankush/benches/develop/apps/frappe/frappe/core/doctype/user/patches/improve_indexing.py and updated patches.txt

建议在路径中创建一个包含补丁编号和名称的文件，
并将其添加到应用中的补丁包（目录）中。然后，你可以将补丁模块的
点分路径添加到 patches.txt 中。

Frappe 中遵循的目录结构如下所示：

frappe
└── patches
└── 4_0
└── my_awesome_patch.py

可以通过添加如下一行来将补丁添加到 patches.txt：

frappe.patches.4_0.my_awesome_patch

在 execute 函数中可用的元数据（即 DocType）将是应用中的 JSON 文件所对应的
最新版本。但是，你将无法访问系统任何先前状态的元数据。

一次性 Python 语句

你还可以使用以下语法在 patches.txt 中添加一次性 Python 语句：
execute:{python 语句}

例如：
execute:frappe.get_doc(“User”, “Guest”).save()

注意：patches.txt 中的所有行必须是唯一的。如果你想运行某行两次，
可以通过添加不同的注释使其唯一。

例如：

execute:frappe.installer.make_site_dirs() #2014-02-19

如何将文档类型变更迁移到生产环境

1. 文档类型 / 架构变更

如果您处于 developer_mode 中，每个 DocType 对应的 .json 文件会自动更新。

当您在生产环境中通过 --latest 或 bench update 进行更新时，这些更改也会同步到站点的架构中！

2. 权限

权限不会自动更新，因为用户可能已经对其进行了修改。若要更新权限，您可以在应用的 patches.txt 中添加一个新的补丁。

执行：frappe.permissions.reset_perms(“[docype]”)

后台任务失败邮件通知

Frappe 按以下方式处理任务失败：

  1. 如果任务失败（抛出异常），它会被记录在调度器日志和 logs/worker.error.log 中。
  2. 系统会保留一个锁文件，如果锁文件存在，则不再运行该任务。
  3. 如果锁文件存在时间超过 10 分钟，则会抛出 LockTimeoutError 异常。

您可以通过编写一个内容如下的文件 sites/common_site_config.json 来配置调度器错误的邮件通知。

{
  "celery_error_emails": {
 "ADMINS": [
 [
 "Person 1",
 "[email protected]"
 ],
 [
 "Person2 ",
 "[email protected]"
 ]
 ],
 "SERVER_EMAIL": "[email protected]"
 }
}

一个限制是，它将使用本地邮件服务器（端口 25）来发送邮件。

物料管理

版本 14 中的新功能

包（Package）是轻量级应用，您可以直接从框架界面（Framework UI）构建。包与应用程序非常相似，是模块定义（Module Defs）的集合。

您可以直接从框架界面（无需使用命令行）通过 DocTypes、服务器脚本（Server Scripts）、网页（Web Page）等来创建应用。高质量的应用可以直接从框架中构建。这些应用可以打包成一个“包”，然后导入到其他站点。

要将模块添加到包中，您需要设置其“包”属性。此功能适用于“自定义”模块定义。

创建包

您可以通过创建包对象来创建新包。您可以设置 README 和许可证（LICENSE）。包的设计方式使其可以推送到 git 仓库。

创建包后，您可以将自定义模块定义添加到该包中。

制作包发布版本

包发布会将所有包模块像应用一样导出到 [bench]/sites/[site]/packages 文件夹中，然后将该文件夹打包成 gzip 压缩的 tar 文件 [package]-[version].tar.gz。

然后您可以下载该包发布版本并将其导入到另一个站点。

导入包

您可以创建一个包导入，并将导出的包附加到新站点上。如果您勾选“激活”，该包将被解压到 [bench]/sites/[sitename]/packages 文件夹中（现有文件将被覆盖）。

然后系统会像应用迁移一样将此包迁移到数据库中。除非勾选了“强制”选项，否则未更改的文件将被跳过。

系统会创建包含输出信息的日志。