From 460cc2849254baaada570d832f9e737d132d2580 Mon Sep 17 00:00:00 2001 From: HynLcc Date: Sun, 9 Aug 2026 00:59:44 +0800 Subject: [PATCH] docs: document app site info and refresh the computed outbox admin page - app builder: new Custom site info dialog for favicon, title, and description, with the republish requirement - computed outbox: replace the stale failed-task list and 10-oldest recovery with the queue job browser and whole-group recovery; add pause duration and runtime worker concurrency - smtp sender: point to the Send Email step output for the mail server's actual rejection detail Co-Authored-By: Claude Opus 5 --- en/basic/admin-panel/computed-outbox.mdx | 37 ++++++++++++++++--- en/basic/ai/app-builder.mdx | 12 ++++++ .../actions/communication/smtp-sender.mdx | 2 + zh/basic/admin-panel/computed-outbox.mdx | 35 +++++++++++++++--- zh/basic/ai/app-builder.mdx | 12 ++++++ .../actions/communication/smtp-sender.mdx | 2 + 6 files changed, 89 insertions(+), 11 deletions(-) diff --git a/en/basic/admin-panel/computed-outbox.mdx b/en/basic/admin-panel/computed-outbox.mdx index 65530f9c..840b2cdc 100644 --- a/en/basic/admin-panel/computed-outbox.mdx +++ b/en/basic/admin-panel/computed-outbox.mdx @@ -7,7 +7,7 @@ description: "Monitor BullMQ delivery and computed task backlog in the Admin Pan Path: Admin Panel → Computed Outbox -Use **Computed Outbox** when formula, lookup, or other computed field values stop updating or take much longer than expected. The page shows the overall task health, recent failures, tasks that may need recovery, and any space whose computed tasks are currently paused. +Use **Computed Outbox** when formula, lookup, or other computed field values stop updating or take much longer than expected. The page shows the overall task health, the jobs moving through the queue, tasks that may need recovery, and any space whose computed tasks are currently paused. ## Read the Health Status @@ -19,7 +19,25 @@ The status beside the page title shows whether computed tasks need attention: | **Degraded** | Teable found failures, timed-out tasks, or a growing backlog. | | **Critical** | BullMQ is unavailable or no worker is available to process tasks. | -When the status needs attention, the page lists the reason. Click the **Failed** count to view recent failed tasks and their failure reasons. +When the status needs attention, the page lists the reason. + +## Find a Task in the Queue + +**Live BullMQ queue** lists the jobs Teable still retains, so you can follow one computed task or look for slow ones. + +Each row is one task by default, and it moves through states in place as Teable retries it. Switch to **Deliveries** when you need the full attempt history of a task or want to hunt for slow runs. + +To narrow the list: + +- Click the state tiles above the table to filter by state: **Waiting**, **Active**, **Delayed**, **Failed**, **Completed (retained)**, and so on. You can select several at once, and hovering a tile explains what that state means. +- Filter by **Space**, **Base**, or **Cause**, search for a task, Base, Space, or error, or set a minimum processing time to surface slow tasks. +- Click a row to open its detail: queue timestamps, delivery lag, processing time, and, for failed deliveries, the full failure reason with the redacted SQL. + +**Completed** does not mean the task did work. The outcome badge says what the delivery actually did: **Processed** ran the task, **No-op** found nothing left to do, **Deferred** rescheduled it for later, and **Parked** means its scope is paused. + +A failed row is the history of one delivery attempt, not a stuck task. The durable task keeps retrying on its own, so read the **Ledger state** column to decide whether to act: **Settled** means a later retry already succeeded, and **Dead letter** links to anomaly maintenance. Settled failures are hidden by default; a banner shows how many there are and lets you reveal them. + +**Clear failed history** removes the retained failed-job records from the queue only. It repairs nothing, and dead letters remain in **Anomaly maintenance**. ## Handle Anomalous Tasks @@ -31,10 +49,10 @@ Each group offers one action, depending on its type: | Anomaly type | Action | What happens | | --- | --- | --- | -| **Dead letter** | **Recover up to 10 oldest** | Restores the 10 oldest failures in that group and redelivers them. Newer failures in the same group, and every other group, stay untouched. | +| **Dead letter** | **Recover entire group** | Restores every dead letter currently in that group to the durable queue and redelivers them. Every other group stays untouched. | | **Timed out** | **Re-arm latest timeout** | Wakes the queue for the newest task in the group so a worker can take it over. | -After a batch recovery, Teable reports how many tasks it recovered, delivered, deferred, or found in conflict, and how many are still waiting. Run the action again to work through a large group. +After a group recovery, Teable reports how many tasks it restored, how many were newly queued or already queued, and how many were delivered or deferred. Workers then consume the group under the current concurrency and task-splitting limits. ## Pause Computed Tasks for a Space @@ -43,10 +61,17 @@ When one space's computed tasks are making an incident worse, pause that space i Click **Pause a space**. Search by space ID or name, then select it from the results. + Set **Pause duration** to 15, 30, 60, or 120 minutes. Note the incident or maintenance window in **Reason**. Click **Confirm pause**. -A pause only stops workers from claiming new computed tasks for that space. Tasks already running are not interrupted, and matching tasks wait until you resume rather than being dropped. +A pause only stops workers from claiming new computed tasks for that space. Tasks already running are not interrupted, and matching tasks wait until the pause ends rather than being dropped. + +A pause always expires on its own, and two hours is the longest you can set. If the incident outlasts it, pause the space again from this page. The list shows every active pause with who created it, why, and when it auto-resumes, along with how many pending tasks the active pauses are holding, so you can judge the backlog a resume will release. To lift one early, click **Resume** on its row and confirm. + +## Adjust Worker Concurrency + +**Per-process concurrency** in the queue section shows how many computed tasks each worker process handles at once. Click it to set a cluster-wide override; every worker picks it up within about 15 seconds, with no restart. **Reset to default** removes the override and returns each process to its own environment setting. -The list shows every active pause with who created it, why, and when it auto-resumes. To release one, click **Resume** on its row and confirm. Workers can then claim that space's computed tasks again. +Higher concurrency puts more load on your database. Each Base is separately limited to 2 concurrent tasks across the cluster, so raising this value mainly helps when many Bases are waiting at the same time. diff --git a/en/basic/ai/app-builder.mdx b/en/basic/ai/app-builder.mdx index b5184f37..1049a07a 100644 --- a/en/basic/ai/app-builder.mdx +++ b/en/basic/ai/app-builder.mdx @@ -159,6 +159,18 @@ You can also use an available subdomain under `teable.app` and edit the `teable. className="docs-screenshot" /> +### Custom Site Info + +Use **Custom site info** in the **Publish** menu to set the browser tab icon, page title, and description of the published app. The dialog previews how they look together as you edit. + +| Setting | What it controls | +| --- | --- | +| **Favicon** | The icon shown in the browser tab. Upload a PNG, JPEG, WebP, SVG, or ICO file up to 5 MB; 32×32 is the recommended size. Remove the uploaded file to return to the default Teable icon. | +| **Title** | The page title, up to 120 characters. | +| **Description** | The site description in the page metadata, up to 500 characters. | + +Leave a field empty to keep the value App Builder wrote for you. Saving applies the change to the app preview environment; the published app uses it only after you republish. + ### App Login Click **Add login** in the app header to require visitors to sign in before they can use the app. Once login is configured, the button changes to **Login settings**. diff --git a/en/basic/automation/actions/communication/smtp-sender.mdx b/en/basic/automation/actions/communication/smtp-sender.mdx index 9b73fa0b..cbfe7401 100644 --- a/en/basic/automation/actions/communication/smtp-sender.mdx +++ b/en/basic/automation/actions/communication/smtp-sender.mdx @@ -56,6 +56,8 @@ In the **Send Email** action, click the transport configuration option to set up ## Common errors and fixes +When a run fails to send, open the workflow's **Run history** and check the output of the **Send Email** step. For a custom SMTP server, the step reports the rejection your mail server returned: its reply code, the SMTP command that failed, the rejected recipients, and the host. Match that against the causes below. + | Error | Likely Cause | Fix | |---|---|---| | **Connection refused** | Wrong host or port | Double-check the SMTP host and port. Try switching between 465 and 587 | diff --git a/zh/basic/admin-panel/computed-outbox.mdx b/zh/basic/admin-panel/computed-outbox.mdx index df1fb6ab..097628e4 100644 --- a/zh/basic/admin-panel/computed-outbox.mdx +++ b/zh/basic/admin-panel/computed-outbox.mdx @@ -7,7 +7,7 @@ description: "在管理面板中监控 BullMQ 投递和计算任务积压。" 路径：管理面板 → 计算任务队列 -当公式、Lookup 等计算字段长时间没有更新，或更新时间明显变长时，可以打开 **计算任务队列**。页面会显示计算任务的整体状态、最近失败任务、可能需要恢复的异常任务，以及当前被暂停计算的空间。 +当公式、Lookup 等计算字段长时间没有更新，或更新时间明显变长时，可以打开 **计算任务队列**。页面会显示计算任务的整体状态、队列中正在流转的任务、可能需要恢复的异常任务，以及当前被暂停计算的空间。 ## 查看健康状态 @@ -19,7 +19,25 @@ description: "在管理面板中监控 BullMQ 投递和计算任务积压。" | **需关注** | Teable 发现任务失败、执行超时或积压。 | | **严重** | BullMQ 不可用，或当前没有可处理任务的 Worker。 | -状态需要关注时，页面会显示具体原因。点击 **失败** 数量，可以查看最近失败的任务和原因。 +状态需要关注时，页面会显示具体原因。 + +## 在队列中定位任务 + +**BullMQ 实时队列** 会列出当前保留的任务，可以用它跟踪某个计算任务，或者找出耗时偏长的任务。 + +列表默认一个任务一行，Teable 重试时该行会原地切换状态。需要查看某个任务的完整尝试记录，或排查慢任务时，切换到 **投递明细**，可以看到每一次唤醒投递。 + +缩小范围的方式： + +- 点击表格上方的状态卡片（**等待中**、**执行中**、**延迟任务**、**失败**、**已完成（保留）** 等）按状态筛选，可以多选；悬停卡片会说明该状态的含义。 +- 按 **Space**、**Base**、**触发原因** 筛选，搜索任务、Base、Space 或错误，也可以设置最短处理耗时来找出慢任务。 +- 点击某一行可以查看详情：入队和投递时间、投递延迟、处理耗时；失败的投递还会给出完整失败原因和脱敏后的 SQL。 + +**已完成** 不代表任务真的做了事情。执行结果徽章说明这次投递的实际结果：**已执行** 表示执行了计算任务，**无操作** 表示已无事可做，**已推迟** 表示改到稍后重试，**已挂起** 表示所在范围被暂停。 + +失败行只是某一次投递尝试的历史记录，不代表任务卡住，持久任务会自行继续重试。是否需要介入，要看 **账本状态** 一列：**已了结** 表示后续重试已经成功，**已成死信** 可以跳转到异常任务维护。已了结的失败记录默认隐藏，横幅会显示条数并支持展开。 + +**清理失败记录** 只会清掉队列中保留的失败任务记录，不会修复任何问题，死信仍然保留在 **异常任务维护** 中。 ## 处理异常任务 @@ -31,10 +49,10 @@ description: "在管理面板中监控 BullMQ 投递和计算任务积压。" | 异常类型 | 操作 | 效果 | | --- | --- | --- | -| **死信** | **恢复最早一批（最多 10 条）** | 恢复该组中最早的 10 条失败任务并重新投递。同组中更晚的任务，以及其他问题组，都不受影响。 | +| **死信** | **恢复整个问题组** | 把该组当前的全部死信一次性恢复到持久队列并重新投递。其他问题组不受影响。 | | **执行超时** | **重新唤醒最近一条超时** | 为组内最新任务重新唤醒队列，由 Worker 接管执行。 | -批量恢复完成后，Teable 会给出恢复、投递、延迟投递和冲突的条数，以及仍在等待的数量。问题组较大时，可以重复执行该操作逐批处理。 +恢复完成后，Teable 会给出恢复条数、新入队与已在队列的条数，以及已投递和延迟投递的条数。随后 Worker 会按现有的并发和任务分片限制逐步消费这一组任务。 ## 暂停某个空间的计算任务 @@ -43,10 +61,17 @@ description: "在管理面板中监控 BullMQ 投递和计算任务积压。" 点击 **暂停空间**。 按 Space ID 或名称搜索，然后在结果中选中。 + 在 **暂停时长** 中选择 15、30、60 或 120 分钟。 在 **原因** 中写明事故或维护窗口。 点击 **确认暂停**。 暂停只会阻止 Worker 领取该空间新的计算任务。已经在执行的任务不会被中断，匹配到的任务会一直等待，不会被丢弃。 -列表会显示所有生效中的暂停，包括操作人、原因和自动恢复时间。需要解除时，点击对应行的 **恢复** 并确认，Worker 随后即可重新领取该空间的计算任务。 +暂停到期后会自动解除，最长 2 小时。处理时间超出时，可以在本页面重新暂停续期。列表会显示所有生效中的暂停，包括操作人、原因和自动恢复时间，并显示这些暂停当前积压了多少待处理任务，便于判断恢复后会释放多少工作量。需要提前解除时，点击对应行的 **恢复** 并确认。 + +## 调整 Worker 并发 + +队列区域的 **每进程并发** 表示每个 Worker 进程同时处理多少个计算任务。点击它可以写入集群级覆盖值，所有 Worker 约 15 秒内生效，无需重启。点击 **恢复默认** 会清除覆盖值，各进程回到自身环境变量的设置。 + +并发调高会增加数据库压力。同一个 Base 另受集群级并发上限 2 的限制，因此调大该值主要在多个 Base 同时排队时才有帮助。 diff --git a/zh/basic/ai/app-builder.mdx b/zh/basic/ai/app-builder.mdx index 922009d1..f6617ce0 100644 --- a/zh/basic/ai/app-builder.mdx +++ b/zh/basic/ai/app-builder.mdx @@ -169,6 +169,18 @@ Teable 应用构建器 (App Builder) 允许您在不编写代码的情况下， className="docs-screenshot" /> +### 自定义站点信息 + +在 **发布** 菜单中打开 **自定义站点信息**，可以设置已发布应用的浏览器标签页图标、站点标题和描述。编辑时弹窗会实时预览这三项的整体效果。 + +| 设置项 | 作用 | +| --- | --- | +| **网站图标** | 浏览器标签页显示的图标。支持上传 PNG、JPEG、WebP、SVG 或 ICO 文件，大小不超过 5MB，建议尺寸 32×32。移除已上传的文件即可恢复默认的 Teable 图标。 | +| **标题** | 站点标题，最多 120 个字符。 | +| **描述** | 页面元信息中的站点描述，最多 500 个字符。 | + +留空的字段会保留应用构建器生成的原值。保存后改动会应用到应用预览环境；已发布应用需要重新发布后才会生效。 + ### 应用登录 在应用顶部点击 **添加登录**，可以要求访问者登录后再使用应用。配置后，该按钮会变为 **登录设置**。 diff --git a/zh/basic/automation/actions/communication/smtp-sender.mdx b/zh/basic/automation/actions/communication/smtp-sender.mdx index 3a0546f5..4ebf54e9 100644 --- a/zh/basic/automation/actions/communication/smtp-sender.mdx +++ b/zh/basic/automation/actions/communication/smtp-sender.mdx @@ -48,6 +48,8 @@ description: "配置自定义 SMTP 服务器和发件人信息用于自动化邮 ## 常见错误和解决方法 +发送失败时，打开工作流的 **运行历史**，查看 **发送邮件** 步骤的输出。使用自定义 SMTP 服务器时，该步骤会给出邮件服务器返回的拒绝信息：响应码、失败的 SMTP 命令、被拒绝的收件人和服务器地址，可以据此对照下表定位原因。 + | 错误 | 原因 | 解决方法 | |---|---|---| | 连接超时 | 服务器地址或端口错误 | 检查服务器地址拼写和端口号。465 对应 SSL，587 对应 TLS，不要混用 |