分类： Frappe

用户记录上的电子邮件字段在用户保存后即被禁用。要更改它，请使用重命名，而不是该字段本身。这会立即更改用户的登录地址：用户会从所有设备上退出登录，旧地址将不再接受登录或密码重置，但密码保持不变。

为什么电子邮件字段被禁用

用户的电子邮件不仅仅是一个字段。它也是用户的唯一 ID（其文档名称）——创建用户时，Frappe 会将 name 设置为该电子邮件地址。所有针对用户写入的记录，包括分配、权限、文档所有权、Created By 和 Modified By 列，都通过该 ID 关联。直接更改该字段会破坏这些关联，因此 Frappe 只允许通过重命名进行更改，该操作会一次性更新 ID 以及所有指向它的记录。

更改用户的电子邮件地址

开始之前

• 您需要系统管理员角色。
• 您无法重命名 Administrator 或 Guest 账户——请参阅“如果您误重命名了唯一的管理员账户”。

步骤

1. 转到用户列表，打开您要更改电子邮件的用户。
2. 点击表单右上角的菜单 (⋮) 按钮。
3. 选择重命名。
   
4. 在新名称字段中，输入新的电子邮件地址。
   
5. 点击重命名。

Frappe 会将用户的 ID 以及所有关联记录（分配、权限、文档历史）更新为新地址。对于历史记录较长的用户，这可能需要几秒钟——运行期间请勿关闭标签页。

重命名后会发生什么

• 用户会在所有地方退出登录。重命名完成后，Frappe 会立即结束该用户在每个浏览器和设备上的所有活动会话。
• 密码不会更改。用户使用新电子邮件和现有密码重新登录。不会自动发送密码重置邮件。
• 旧电子邮件立即失效，包括用于忘记密码。如果有人尝试使用，会看到 User does not exist——这是预期行为，不是错误，因为该记录不再使用该名称。
• 文档历史得以保留。现有文档上的评论、分配以及 Created By / Modified By 记录仍会在新电子邮件下正确显示该用户。

两个用户可以共用一个电子邮件地址，或重用已禁用用户的电子邮件吗？

1. 电子邮件是用户的文档 ID，因此它在所有用户（包括已禁用的用户）中必须唯一。尝试创建用户或将用户重命名为已被使用的电子邮件（即使是已禁用用户的电子邮件），都会失败，并提示该 ID 已存在。

如果多个人需要阅读发送到一个地址的邮件，例如共享的 sales@ 收件箱，请为每个人分配各自的用户和各自唯一的电子邮件，并在您的邮件提供商处将所有这些地址指向该共享收件箱：为每个人设置不同的别名（sales-priya@、sales-arjun@），或者如果您的提供商支持，使用同一地址的加号变体（sales+priya@）。每个用户仍然拥有一个真实且唯一的登录地址，而所有邮件都会进入同一个收件箱。

作为最后的手段，如果您无法创建更多地址，系统管理员可以在系统设置 → 登录中开启允许使用用户名登录。这样用户就可以使用用户名而不是电子邮件登录，因此电子邮件本身可以填写占位值。这只会改变他们的登录方式——他们仍然不会收到发送到该占位地址的系统邮件通知，而且每个用户的电子邮件仍然必须唯一。

如果您误重命名了唯一的管理员账户

字面意义上的 Administrator 账户永远无法被重命名——Frappe 会直接阻止。因此，“管理员账户的电子邮件被更改了”始终意味着某个系统管理员级别的用户被重命名或重新创建，而不是 Administrator 本身。

如果您仍有可用的会话或另一个系统管理员账户：

1. 使用新电子邮件地址和该账户之前的相同密码登录——重命名并未重置密码。
2. 如果您不知道新电子邮件被改成了什么，请让另一位系统管理员打开用户列表，按名称、电话号码或角色查找该记录，然后将当前电子邮件告诉您。

如果没有人能访问任何系统管理员账户：

• 在 Frappe Cloud 上，打开您的仪表板，转到通知 → 请求，并批准来自支持团队的站点访问请求，以便他们可以从他们那边查找或重置该账户。
• 拥有服务器访问权限时，系统管理员可以直接重置管理员本人的密码：bench --site [site-name] set-admin-password [new-password]。这会重置管理员的密码，而不是被重命名用户的密码——请用它重新以管理员身份登录，然后在那里修复被重命名的账户。

相关

• 更改现有用户的电子邮件 ID 或重命名用户
• 我收不到密码重置、登录链接或双重身份验证电子邮件

当你在保存、提交或重命名文档时，如果另一个事务对同一行持有锁，你可能会看到 Lock wait timeout exceeded 或 Deadlock found when trying to get lock。这通常发生在并发提交、长时间运行的后台任务，或重命名一个被许多其他文档链接的文档时。

错误信息

你会看到以下之一，通常出现在“服务器错误”对话框中或错误日志里：

pymysql.err.OperationalError: (1205, 'Lock wait timeout exceeded; try restarting transaction')

pymysql.err.OperationalError: (1213, 'Deadlock found when trying to get lock; try restarting transaction')

在 MariaDB 11.6.2 及更高版本中，你在重命名或繁忙保存时也可能看到这个：

pymysql.err.OperationalError: (1020, "Record has changed since last read in table '<table>'")

<p>Frappe 将这三者都视为死锁，因为从用户的角度来看，MariaDB 较新的快照隔离检查（错误 1020）与错误 1213 是同一个问题。</p>
<h2 id="why-this-happens"><strong>为什么会发生</strong></h2>
<p>InnoDB 是 Frappe 使用的数据库引擎，它会在事务更新或插入某一行时立即锁定该行，并一直持有该锁，直到事务提交或回滚。如果第二个事务需要同一行，它就会等待。默认情况下，MariaDB 最多等待 50 秒（<code>innodb_lock_wait_timeout）后放弃并抛出错误 1205。如果两个事务同时互相等待对方的锁，MariaDB 根本不会等待：它会立即检测到循环等待，回滚其中一个事务，并抛出错误 1213（或者自 MariaDB 11.6.2 起，抛出错误 1020）。

重命名是一个特殊情况。重命名文档会更新其自身的行，然后更新所有指向它的 DocType 中的每个 Link 或 Dynamic Link 字段，全部在同一个事务内完成。重命名一个被许多其他记录引用的文档（例如仓库、物料组或工作流操作）会在多个表上持有锁更长时间。在重命名运行期间，任何其他触及这些相同行的事务（例如针对该仓库保存销售发票）都必须等待，并可能超时。
常见触发原因：

多个用户同时提交更新同一链接记录的文档，例如针对同一客户或仓库的销售发票。
一个后台任务（库存重算、计划任务、批量更新）在用户保存相关文档时持有长事务。
一个浏览器标签页或 API 会话保持打开状态，带有未提交的更改，仍然持有锁。
重命名一个被许多其他文档链接的文档。

对于后台任务，Frappe 已经会自动重试。如果 execute_job 遇到错误 1205 或 1213（或 1020，因为 Frappe 将其映射到相同的死锁检查），它会回滚并以递增的延迟重试该任务最多 5 次。从桌面端进行的保存或提交不会自动重试——用户会立即看到错误。
如何修复

打开 系统控制台（在顶部搜索栏中搜索）。你需要 系统管理员 角色。
在 数据库进程 下，打开 显示进程列表。表格会自动填充，无需点击执行，并显示每个打开的数据库会话、其状态以及已运行的时间。


查找 状态 不是空闲的会话，或者 时间 较高的会话。其 信息 列显示正在运行的查询，如果是一个正在等待其他资源的打开事务，则为空。
要查看死锁的完整详情，包括是哪个表和行导致的，请从数据库控制台（bench --site <site-name> mariadb</site-name>）运行 SHOW ENGINE INNODB STATUS\G，并阅读 最近检测到的死锁 部分。
如果某个会话卡住并持有锁，请从同一数据库控制台结束它：

KILL <id>;
</id>
使用进程列表中的 Id。在 Frappe Cloud 上，你无法自行运行 KILL；请提交支持工单并附上进程列表输出。

6. 如果阻塞会话属于后台工作进程，请重启工作进程，而不是直接终止数据库会话：bench restart。如果只有调度器卡住，bench scheduler resume --site <site-name></site-name> 可以在不进行完整重启的情况下恢复它。

7. 重试保存、提交或重命名。
如何预防

后台任务在遇到死锁或锁等待超时时会自动重试最多 5 次，因此繁忙时段的一次性错误通常会自动清除。只有在之后仍然失败，或者用户在桌面端立即被阻塞时才需要介入。
在非繁忙时段重命名一个被许多记录链接的文档（仓库、物料组或成本中心）。
在自定义脚本或报表中，分批提交，而不是在一个事务中循环处理数千条记录。
关闭你保持空闲且带有未保存或未提交更改的浏览器标签页或 API 会话。

如果你使用的是不受支持的版本
如果你的 应用版本 显示 Frappe 或 ERPNext v14 或更早版本，请升级。在这些工单中的几个案例里，真正的原因是较新版本已经修复的慢查询或锁定行为，而生命周期结束的版本不在性能调查的范围内。
如果这不能解决问题
如果错误在非繁忙、非并发使用的情况下仍然持续发生，请提交支持工单，并提供确切的错误文本、您当时正在保存、提交或重命名的文档、您的应用版本，以及错误发生时的进程列表输出（或系统控制台截图）。
相关内容

后台任务
系统控制台
性能分析与监控

你点击了忘记密码、通过电子邮件链接登录，或者你开启了双重身份验证（2FA），但包含重置链接、登录链接或验证码的邮件始终没有送达。在所有这些情况下，Frappe 都会将邮件加入队列，并依赖站点自身的发件邮件设置来实际发送它——因此，解决办法几乎总是出在电子邮件账户或电子邮件队列中，而不是密码重置或 2FA 功能本身。

错误信息

通常屏幕上根本不会显示任何错误——你只是一直收不到邮件。如果确实有错误，通常是下面这个，在你尝试通过电子邮件链接登录时会以弹窗形式显示：

Please setup default outgoing Email Account from Tools > Email Account

或者，如果已配置账户但配置有误，会显示在电子邮件队列条目自身的错误字段中：

Invalid Outgoing Mail Server or Port: Connection unexpectedly closed

如果你遇到的是通用的服务器错误，或者提到 reset_password 的堆栈跟踪，而不是上述任一情况，请跳到“如果这样仍无法解决”。

为什么会发生这种情况

Frappe 不会在你请求的那一刻就发送密码重置、登录链接或 2FA 邮件。它会将邮件写成一个新的电子邮件队列条目，并从那里发送，使用被标记为默认发件的那个电子邮件账户。双重身份验证邮件也走同样的路径：如果双重身份验证方式是电子邮件或短信，Frappe 会在每次登录时以同样的方式通过邮件或短信发送验证码；即使使用 OTP 应用方式，在用户首次开启 2FA 时，Frappe 也会在身份验证器应用被视为注册完成之前，先发送一封设置确认邮件。

因此，所有这三种症状——收不到重置邮件、收不到登录链接、收不到 2FA 验证码——通常都归结为同样的两件事：是否存在一个可用的默认发件电子邮件账户，以及电子邮件队列是否实际发送了该条目。如果这两者都不是原因，邮件仍可能被送达，但被当作垃圾邮件过滤掉，或者因队列自身的发送间隔而被延迟。

如何解决

1. 打开电子邮件账户列表（在 Awesome Bar 中搜索“Email Account”）。检查至少有一个账户勾选了启用发件，并且在发件（SMTP）设置下恰好有一个账户勾选了默认发件。如果没有任何账户勾选，请打开一个可用的账户，勾选这两个复选框，然后保存。
   
2. 打开电子邮件队列列表，找到你期望的那封邮件的条目（按收件人筛选，或按最后更新时间排序以查看最新的）。检查其状态：

• 错误：打开该条目并阅读错误字段。此处出现服务器/端口/身份验证相关的消息，意味着默认发件账户的 SMTP 设置不正确——请在电子邮件账户中修正它们并重新发送。
• 未发送或发送中：队列尚未将其发出。默认情况下，队列每 4 分钟发送一次（站点的 scheduler_interval）。等待几分钟，或者请拥有 bench 访问权限的系统管理员立即运行它：bench --site [site-name] execute frappe.email.queue.flush。
• 已发送：在 Frappe 这一侧投递已成功。请转到第 3 步。
  

3. 如果队列显示已发送但邮件仍未送达，请先检查收件人的垃圾邮件或废件文件夹。如果邮件一直被过滤，很可能是发送域名缺少该电子邮件账户域名的 SPF 或 DKIM DNS 记录——请让管理该域名 DNS 的人员按照邮件服务商公布的值添加它们。
4. 在 Frappe Cloud 上，如果站点使用的是内置的电子邮件投递服务应用而不是你自己的 SMTP 账户，请确认它没有达到套餐的发送上限。请参阅“升级电子邮件投递服务套餐”。电子邮件配置本身的产品支持取决于你站点的支持计划层级。
5. 如果缺失的邮件具体是 2FA 验证码或设置邮件，请先重新检查第 1 步——这是同一个默认发件原因，而不是单独的 2FA 问题。如果第 1 步已经正确，请打开系统设置 → 登录，确认双重身份验证方式与你期望的一致（OTP 应用、短信或电子邮件）。
   

若要在不等待邮件的情况下让被锁定的用户重新登录，系统管理员可以在系统设置 → 登录中取消勾选启用双重身份验证，临时为所有人关闭 2FA；或者通过从全部角色中移除双重身份验证权限，将其限定到特定角色。在底层邮件问题解决后，再重新开启它。

如果这样仍无法解决

• 如果错误是提到 reset_password 或 AttributeError 的服务器堆栈跟踪，而不是缺少默认发件账户，那么这是代码层面的问题，通常与最近的版本升级有关，而不是电子邮件配置问题。请提交支持工单，附上来自错误日志的完整堆栈跟踪以及站点的 Frappe 和应用版本（帮助 → 关于）。
• 如果电子邮件队列条目显示已发送，SPF/DKIM 已经正确，但电子邮件仍然从未到达，请提交支持工单。请包含站点名称、电子邮件队列条目的名称和状态，以及这是影响一个用户还是所有人。

如何预防

• 只保留一个标记为默认发件的电子邮件账户，并在任何更改后通过给自己发送密码重置或登录链接电子邮件来进行测试。
• 如果您添加或更改电子邮件账户，请重新检查默认发件——新账户很容易忘记设置，或者两个账户都标记为发件但都没有设为默认。

相关

• 电子邮件账户
• 如果收件人没有收到电子邮件怎么办
• 设置双因素认证
• 升级电子邮件投递服务计划

突然间，就在一次 Frappe 更新之后，你一打开打印视图或尝试下载 PDF，所有打印格式（或某个特定格式）就立刻报错。错误信息只给出了行号，却没有说明是哪个格式，所以很难看出该修什么。

错误信息

你会看到下面其中一种，可能出现在打印视图的对话框中，也可能出现在 PDF/下载的响应里：

Print Format Error

Error in print format on line 19: 'NoneType' object is not callable

或者是更完整的版本，出现在你从 PDF 下载链接得到的服务器错误页面中：

File "apps/frappe/frappe/templates/print_formats/standard.html", line 19, in top-level template code

{{ render_field(df, doc, no_of_cols) }}

File "env/lib/python3.x/site-packages/jinja2/sandbox.py", line 401, in call

return __context.call(__obj, *args, **kwargs)

TypeError: 'NoneType' object is not callable

...

frappe.exceptions.PrintFormatError: Error in print format on line 19: 'NoneType' object is not callable

还有一种相关的情况，显示的是 KeyError 或其他 Jinja 异常，而不是 NoneType，但同样呈现“所有打印格式都挂了”的模式。原因和下面的修复方法是一样的。

为什么会这样

打印格式是通过 Jinja 渲染的：html 模板通过 Jinja 的沙箱调用 Python 函数并读取文档字段。'NoneType' object is not callable 的意思是 Jinja 试图把某个东西当作函数来调用，但那个东西的值是 None——通常是一个空字段（当 备注 为空时就是 {{ doc.remarks() }}），或者是沙箱无法解析的模板宏。

大多数“更新后所有打印格式都坏了”的报告，都能追溯到 Frappe Framework 本身的一次短暂回归，出在 standard.html 模板上——所有内置打印格式和基于 Builder 的打印格式都共用这个模板。一次核心改动导致其中一个模板宏在两个版本之间的短暂窗口内返回了 None。Frappe 修复这类问题很快（几小时到几天内），并以补丁版本发布修复，但在你的站点升级到那个版本之前，所有打印和 PDF 都会以同样的方式失败。同一个模板上已经不止一次发生过这种情况，所以“先更新看看是否修好了”是合理的第一步，而不是一次性的做法。

如果只有 一个 打印格式失败，其余都正常，那原因就在这个格式本身：某个自定义打印格式（或合作伙伴定制过的格式）的 Jinja 或自定义 HTML 调用了某个字段、doctype 方法或打印模板钩子，而应用更新把它删除了、重命名了，或者对某些文档留空了。

如何修复

1. 打开文档，点击打印图标，把 打印格式 切换到另一个（内置格式，或 标准）。如果它能正常渲染，问题就出在你原来用的那个格式上——跳到第 4 步。如果所有格式都失败，问题就在 Frappe 本身——继续第 2 步。
   
   
   
2. 阅读 traceback，确认它与本问题相符，并找出失败的位置。在打印视图中，重新选择出错的格式以查看对话框；从 PDF 下载链接（或附带 PDF 的邮件/报表）打开完整的服务器错误页面——那里有完整的 traceback。
   
   
   

最后一行会给出异常名称，如果是打印格式特有的错误，还会给出你模板中的行号：

如果失败发生在后台任务中（定时报表、附带 PDF 的邮件）——也就是没有人能看到对话框——请从 Awesome Bar 打开 错误日志，查找同一文档在相近时间的记录；它带有相同的 traceback。
3. 检查你的应用是否都在匹配的、最新的版本上。打开 帮助 → 关于（或在 bench 目录下运行 bench version），对比 已安装应用 列表：Frappe Framework、你的主应用（ERPNext 等）以及任何自定义应用都应该在同一条版本线上（全是 v15，或全是 v16——不能混用），而且都不应落后于该版本线的最新补丁版本。

如果 Frappe Framework 落后了，就更新它：

bench update

bench --site [site-name] migrate

bench build

bench clear-cache

bench clear-website-cache

即使 bench update 无错误地完成，bench build 和两个清除缓存的命令也很重要——过期的 JS/CSS 构建或缓存的页面会继续显示旧的、损坏的行为。在 Frappe Cloud 上，你不需要自己运行这些：公共（共享）bench 会在每周发布日自动更新；在私有 bench 组上，打开站点仪表盘中的 更新 并应用待处理的更新。
4. 如果只有你自己的自定义打印格式失败，打开它（打印格式 列表，或从打印视图点击 自定义），检查 traceback 指出的那一行。查找某个字段引用——它可能对某些文档为空，却被当作函数调用（用 {{ doc.some_field() }} 而不是 {{ doc.some_field }}），或者从某个模板路径导入的宏被应用更新改掉了。修复模板，或者如果这个格式是在更新之前构建的，就按当前的标准布局重新创建它。

如何预防

• 让 Frappe Framework 和其他应用保持在同一版本线上，并使用该版本线的最新补丁版本——这些故障大多会在某个小版本发布中修复，保持更新即可避免。
• 任何更新之后，在团队重新开始使用站点之前，先用你依赖的每个自定义打印格式各打印一份文档。

如果这样仍不能解决

提交支持工单，并附上：确切的错误文本、打印格式名称、帮助 → 关于中的 Frappe Framework 和应用版本，以及你当时正在打印的文档。如果你有完整的回溯信息（来自服务器错误页面或错误日志），请一并附上——这是支持人员确认这是已知的 Framework 回归问题还是你自己的打印格式问题的最快方式。

相关

• 打印
• 在哪里可以找到标准打印格式

突然间，就在 Frappe 更新之后，你一打开打印视图或尝试下载 PDF，所有打印格式（或某个特定格式）就立刻失败了。错误信息会指出行号，但不会说明是哪个格式，所以很难看出该修什么。

错误信息

你会看到以下之一，可能是在打印视图中的对话框里，也可能是在 PDF/下载响应中：

Print Format Error

Error in print format on line 19: 'NoneType' object is not callable

或者是更完整的版本，出现在你从 PDF 下载链接得到的服务器错误页面中：

File "apps/frappe/frappe/templates/print_formats/standard.html", line 19, in top-level template code

{{ render_field(df, doc, no_of_cols) }}

File "env/lib/python3.x/site-packages/jinja2/sandbox.py", line 401, in call

return __context.call(__obj, *args, **kwargs)

TypeError: 'NoneType' object is not callable

...

frappe.exceptions.PrintFormatError: Error in print format on line 19: 'NoneType' object is not callable

一个相关的版本会显示 KeyError 或其他 Jinja 异常，而不是 NoneType，但同样呈现”所有打印格式都挂了”的模式。原因和下面的修复方法是一样的。

为什么会发生这种情况

打印格式是通过 Jinja 渲染的：html 模板通过 Jinja 的沙箱调用 Python 函数并读取文档字段。'NoneType' object is not callable 的意思是 Jinja 试图把某个东西当作函数来调用，但那个东西求值结果是 None——通常是一个空白字段（当 备注 为空时就是 {{ doc.remarks() }}），或者是沙箱无法解析的模板宏。

大多数”更新后所有打印格式都坏了”的报告，都可以追溯到 Frappe Framework 本身的一个短暂回归问题，出在每个内置打印格式和基于 Builder 的打印格式共用的 standard.html 模板中——一次核心改动导致其中一个模板宏在两次发布之间的短暂窗口内返回了 None。Frappe 会很快修复这些问题（几小时到几天内），并以补丁版本的形式发布修复，但在你的站点升级到那个版本之前，每次打印和 PDF 都会以同样的方式失败。同一个模板上已经不止一次发生过这种情况，所以”先更新，看看是否修好了”是一个合理的首选操作，而不是一次性的做法。

如果只有一个打印格式失败，其余的都正常，那原因就在那个格式本身：某个自定义打印格式（或合作伙伴定制过的格式）的 Jinja 或自定义 HTML 调用了某个字段、doctype 方法或打印模板钩子，而某个应用更新将其删除、重命名，或对某些文档留空了。

如何修复

1. 打开文档，点击打印图标，把 打印格式 切换到另一个（某个内置格式，或 标准）。如果它能正常渲染，问题就出在你之前用的那个格式上——跳到第 4 步。如果所有格式都失败，问题就在 Frappe 本身——继续第 2 步。
   
2. 阅读 traceback，确认它与本问题相符，并找出失败的位置。在打印视图中，重新选择失败的格式以查看对话框；从 PDF 下载链接（或附带 PDF 的邮件/报表）中，改为打开完整的服务器错误页面——那里有完整的 traceback。
   

最后一行会指出异常，对于打印格式相关的错误，还会指出你模板中的行号：

如果失败发生在后台任务中（定时报表、附带 PDF 的邮件）——也就是说没有人能看到对话框——请从 Awesome Bar 打开 错误日志，查找同一时间附近针对同一文档的条目；它带有相同的 traceback。
3. 检查你的应用是否处于匹配的、当前的版本。打开 帮助 → 关于（或在 bench 目录下运行 bench version），对比 已安装应用 列表：Frappe Framework、你的主应用（ERPNext 等）以及任何自定义应用都应处于同一版本线（全部 v15，或全部 v16——不要混用），并且都不应落后于该版本线的最新补丁版本。

如果 Frappe Framework 落后了，请更新它：

bench update

bench --site [site-name] migrate

bench build

bench clear-cache

bench clear-website-cache

即使 bench update 无错误地完成，bench build 和两个清除缓存的命令也很重要——过期的 JS/CSS 构建或缓存的页面可能会继续显示旧的、损坏的行为。在 Frappe Cloud 上，你不需要自己运行这些：公共（共享）bench 会在其每周发布日自动更新；在私有 bench 组上，打开站点仪表板中的 更新 并应用待处理的更新。
4. 如果只有你自己的自定义打印格式失败，请打开它（打印格式 列表，或从打印视图中的 自定义），检查 traceback 指出的那一行。查找某个字段引用——它可能对某些文档是空白的，却被当作函数调用（用 {{ doc.some_field() }} 而不是 {{ doc.some_field }}），或者查找从某个应用更新改变了的模板路径导入的宏。修复模板，或者如果该格式是在更新之前构建的，就基于当前的标准布局重新创建它。

如何预防

• 让 Frappe Framework 和其他应用保持在同一版本线，并处于该版本线的最新补丁版本——大多数这类故障都会在补丁版本中修复，保持最新就能避免它们。
• 在任何更新之后，在团队重新开始使用站点之前，用你依赖的每个自定义打印格式各打印一份文档。

如果这样仍无法解决

请提交支持工单，并附上：确切的错误文本、打印格式名称、从 帮助 → 关于 中获取的 Frappe Framework 和应用版本，以及你当时正在打印的文档。如果你有完整的回溯信息（来自服务器错误页面或错误日志），请一并附上——这是支持团队确认该问题属于已知的 Framework 回归问题，还是你自己的打印格式中的问题的最快方式。

相关内容

• 打印
• 在哪里可以找到标准打印格式

Sentry 是一个错误跟踪和性能监控服务。每当发生错误时，应用程序会向它发送一份报告。Sentry 会将相同的错误归并为一个 issue，显示堆栈跟踪和上下文，并在出现新 issue 时提醒团队。你可以使用 sentry.io 上的托管服务，也可以自行部署。借助 Sentry，你可以在一个地方找到所有站点的生产环境错误，而不必逐个搜索每个站点的错误日志。

概述

当你设置一个环境变量并且站点选择启用遥测后，Frappe 会将意外的服务器错误和 desk JavaScript 错误发送到 Sentry 项目。可选变量可以添加性能跟踪、性能分析和 SQL span。

• 每个 bench 一个 DSN。 DSN 来自进程环境，而不是来自 site_config.json。由同一组 web 和 worker 进程服务的所有站点都会报告到同一个 Sentry 项目。
• 两个开关。 DSN 为进程开启 Sentry SDK。系统设置中的复选框允许发送使用数据以改进应用程序（enable_telemetry）决定每个站点是否发送任何内容。
• 错误跟随错误日志。 在服务器上，当 Frappe 写入一条错误日志时，事件会发送到 Sentry。如果你看到一条错误日志，Sentry 应该也有。
• 站点通过名称区分。 每个事件都会将 Sentry 用户 ID 设置为站点名称，因此你可以在 Sentry 中按站点筛选。

设置

为 web 和 worker 进程设置 FRAPPE_SENTRY_DSN，重启它们，然后在每个应报告的站点上启用遥测。

1. 在 Sentry 中创建一个项目（平台：Python）并复制其 DSN。
2. 将这些变量添加到 Frappe web 服务器（gunicorn）以及每个 bench worker 进程的环境中。使用 supervisor 时，使用每个程序的 environment= 行。使用 Docker 时，在后端和 worker 容器上设置它们。
3. 重启进程。Frappe 仅在进程启动时读取这些变量。
4. 在每个站点上，打开系统设置并勾选允许发送使用数据以改进应用程序。从 CLI 执行：bench --site <site> execute frappe.db.set_single_value --args "['System Settings', 'enable_telemetry', 1]"</site>。
5. 在浏览器中重新加载 desk，以便加载浏览器 SDK。

如果设置了 DSN 但站点的 enable_telemetry 处于关闭状态，该站点不会发送任何内容：没有服务器事件，没有浏览器事件，并且 desk 不会加载 SDK。

捕获的内容

Sentry 会获取开发者可以在代码中修复的错误。Frappe 有意向用户显示的错误则被排除在外。

服务器 SDK 运行时关闭了 Sentry 的默认集成。它不会挂钩 Python logging，因此 frappe.logger().error(...) 不会创建 Sentry 事件。来自 CSSUTILS 日志记录器的事件会被丢弃。

发布版本是 Frappe 版本（服务器上为 frappe.__version__，浏览器中为 frappe.boot.versions.frappe），因此你可以看到是哪个版本引入了错误。

性能监控

设置 SENTRY_TRACING_SAMPLE_RATE 以在 Sentry 中查看缓慢的端点和作业。在繁忙的站点上从低值开始（0.01 到 0.1），因为每个被跟踪的请求都会作为事务计费。

• Web 请求。 Frappe 将 WSGI 应用包装在 Sentry 的中间件中。事务按端点命名：RPC 调用为 /api/method/<dotted.path></dotted.path>，否则为 URL 路径。
• 后台任务。事务以任务的方法命名。计划任务则使用调度器任务类型。任务上下文包含任务 ID、其参数、是否为计划任务，以及它在队列中的等待时间（秒）。
• SQL span。启用 ENABLE_SENTRY_DB_MONITORING 后，每次 frappe.db.sql() 调用都会变成一个带有查询文本的 span，并且每次数据库连接都会添加一条面包屑。这就是你查找 N+1 查询的方法。它也会给每次查询增加开销，所以在繁忙的生产环境中启用前请先测量。
• 性能分析。SENTRY_PROFILING_SAMPLE_RATE 是被追踪事务的一部分，因此 0.5 在追踪率为 0.1 时会分析 5% 的请求。

当这三个变量中的任意一个被设置时，Frappe 还会在每个请求和任务开始时标记作用域（事务名称、站点、用户、追踪 ID）。这仅在启用了遥测的站点上发生。

数据与隐私

错误事件可能包含业务和个人数据。请像对待生产数据库一样对待你的 Sentry 项目，并限制可以读取它的人员。

遥测复选框不涵盖性能数据。选择性加入检查针对错误事件和作用域标签运行。追踪、性能分析和 SQL span 会为进程中的每个请求和任务启动。如果一个 bench 托管了未选择加入的站点，请不要在其上设置这三个性能变量。

对于其他你绝不能存储的内容（例如包含国民身份证号或银行详细信息的字段），请使用 Sentry 的服务器端数据擦除功能。

故障排除

代码位于 frappe/utils/sentry.py、frappe/app.py（Web）、frappe/utils/background_jobs.py（工作进程）、frappe/utils/error.py（log_error 钩子）和 frappe/public/js/sentry.bundle.js（浏览器）中。