Grist

Grist

Grist 是一款现代化的关系型电子表格。它将电子表格的灵活性与数据库的稳健性融为一体。

• grist-core（本仓库——也称为 Grist 社区版）具备运行强大服务器所需的一切，用于托管电子表格。
• grist-desktop 是一款 Linux/macOS/Windows 桌面应用，用于查看和编辑本地存储的电子表格。
• grist-static 是 Grist 的完全浏览器内构建版本，用于在没有后端支持的情况下在网站上显示电子表格。

Grist 由 Grist Labs 开发，这是一家位于纽约市 🇺🇸🗽 的公司。法国政府 🇫🇷 机构 ANCT Données et Territoires 和 DINUM（Direction Interministérielle du Numérique） 也为代码库做出了重要贡献。

grist-core、grist-desktop 和 grist-static 仓库均为开源（Apache License, Version 2.0）。Grist Labs 销售带有附加功能的 Grist 版本。Grist Labs 还在 getgrist.com 提供免费和付费的托管服务， 以及云打包。

有疑问？有反馈？想分享你用 Grist 构建的内容？加入我们的官方 Discord 服务器或访问我们的社区论坛。

要随时了解所有最新动态，你可以订阅 Grist 的月度简报。

https://github.com/user-attachments/assets/fe152f60-3d15-4b11-8cb2-05731a90d273

grist-core 中的功能

要确切了解 grist-core 中包含哪些功能，你可以运行桌面应用，或使用 docker。试用 Grist 最快的方式是访问 docs.getgrist.com 并立即在那里试用电子表格——不过如果你这样做，请阅读 grist-core 中不包含的附加功能列表。

无论你如何试用，你都会很快发现 Grist 是一种数据库/电子表格的混合体，这意味着：

• 列的工作方式与数据库中的列一样：它们有名称，并且存放一种类型的数据。
• 列可以通过公式以电子表格风格填充，并在被引用的单元格发生变化时自动更新。

这种差异可能会让直接从 Excel 或 Google Sheets 过来的人感到困惑。给它一个机会！还有一篇 Grist for Spreadsheet Users 文章可以帮助你入门。如果你来自 Airtable，你会发现这个模型很熟悉（我们还有 Grist vs Airtable 文章可供直接比较）。

以下是 Grist 的一些具体功能亮点（🇫🇷 表示法国政府的重要贡献）：

• Python 公式。
  • 完整支持 Python 语法，包括标准库。
  • 还提供许多 Excel 函数。
  • 一个专门针对公式生成调优的 AI 公式助手（可通过 OpenRouter 或任何 OpenAI 兼容端点与 OpenAI、Llama 以及许多其他模型配合使用）。
  • 一个用于诊断缓慢公式的 公式计时器。
• 一种可移植、自包含的格式。
  • 基于 SQLite，这是部署最广泛的数据库引擎。
  • 任何能读取 SQLite 的工具都可以从 Grist 文件中读取数值和文本数据。
  • 支持你可以放心完整恢复的备份。
  • 非常适合在不同主机之间迁移。
• 可以使用 grist-static 在静态网站上显示——无需特殊服务器。
• 一个自包含的桌面应用，用于本地查看和编辑：grist-desktop。
• 便捷的编辑和格式化功能。
  • 选项和选项列表，用于为记录添加彩色标签。
  • 引用和引用列表，用于交叉引用其他表中的记录。
  • 双向引用，可在表之间自动同步。
  • 附件，用于在记录中包含媒体或文档文件。
  • 日期和时间、开关，以及货币等特殊数值类型，都有专门的编辑器和格式化选项。
  • 条件格式，让你可以用公式控制单元格样式，以突出重要信息。
  • 文本单元格中的 Markdown 格式。
• 拖放式仪表板。
  • 用于可视化的图表、卡片视图和日历小组件。
  • 用于跨分组求和与计数的摘要表。
  • 小组件链接可简化数据筛选和编辑。 Grist 有一种独特的可视化方法，你可以布置并链接不同的小组件来一起显示， 而不必把混杂的内容塞进一张表里。
  • 筛选栏，用于快速切片和切块。
  • 复制小组件，快速构建视图的变体。
  • 比较文档，查看发生了什么变化。
• 增量导入。
  • 从银行导入最近三个月活动的 CSV……
  • ……一个月后再导入新活动，无需费力，也不会重复。
• 原生表单。创建可直接填入电子表格的表单，无需费力。
  • 支持文件附件、隐藏字段，以及通过 URL 参数预填充。
• 集成。
  • 一个 REST API，带有交互式 API 控制台、Zapier 操作/触发器，以及类似集成工具的支持。
  • 导入/导出到 Google Drive、Excel 格式、CSV。直接从 Airtable 导入。
  • 通过外部托管的自定义小组件链接数据。
  • 可配置的传出 webhooks，支持授权标头、列特定触发器和公式条件。
  • 服务账户，用于精细调整 API 访问（🇫🇷）。
  • SCIM，用于标准用户和组配置（🇫🇷）。
• 大量模板帮助你快速开始，从投资研究到组织寻宝活动。
• 访问控制选项。
  • （你需要设置登录才能使用这些选项——参见登录）
  • 共享单个文档、工作区或团队站点。
  • 控制对单个行、列和表的访问。
  • 基于单元格值和用户属性控制访问。
• 协作。
  • 单元格上的评论，支持线程回复和 @ 提及。
  • 实时查看还有谁在查看文档。
  • 建议更改，供他人审查和批准，灵感来自源代码控制工作流。
• 可自行维护。
  • 适用于内网运行和特定合规要求。
  • 使用 getgrist.com 登录，无需运行自己的认证服务器即可轻松认证。
  • 将附件外部存储在兼容 S3 的存储中，以保持 .grist 文件较小（🇫🇷）。
  • HTTP 长轮询，作为 WebSockets 的替代方案，适用于受限网络环境（🇫🇷）。
• 针对不受信任文档的沙箱选项。
  • 在 Linux 上或使用 Docker 时，你可以在单个文档级别启用 gVisor 沙箱。
  • 在 macOS 上，你可以使用原生沙箱。
  • 在任何操作系统上，包括 Windows，你都可以通过 Deno 和 Pyodide 使用基于 Wasm 的沙箱。
• 已翻译成多种语言（🇫🇷）。
• 一个满足 WCAG AA 级要求的高对比度主题（🇫🇷）。
• 无障碍支持，包括屏幕阅读器和跨网格视图、菜单以及页面小组件选择器的键盘导航（🇫🇷）。
• F1 键会调出一些快速帮助。这过去是不言而喻的，但总的来说 Grist 有良好的键盘支持（🇫🇷）。
• 我们会在 𝕏 或 Twitter 或随便什么上发布进展，并发布每月简报。 如果你想了解 Grist 的发展方向，请查看我们的路线图，在我们的论坛中提问，或浏览我们详尽的文档。

grist-core 中没有的功能

如果你通过 getgrist.com 上的托管版本来评估 Grist，请注意它包含一些 grist-core 中不存在的功能。为了确保你看到的内容与 grist-core 中完全一致，你可以运行桌面应用，或使用 docker。

以下列出 Grist 完整版中提供、而 grist-core 中没有的功能，按创建时间排序。如果是自托管，你可以在管理面板中选择 Grist 完整版，从而获得所有这些功能的免费试用。对于个人以及年度总资金少于 100 万美元的小型组织，Grist 完整版是免费的。请在此处了解更多信息。

• GristConnect（2022）
  • 任何拥有让 Discourse 使用其登录信息的站点的网站（例如 WordPress），也可以让 Grist 使用其登录信息。
  • GristConnect 是为特定客户构建的小众功能，你可能并不关心。
• 用于文档存储的 Azure 后端（2022）
  • 使用 grist-core，你可以将文档版本存储在任何兼容 S3 的服务中，这涵盖了很多服务，但不包括 Azure 本身。Azure 后端填补了这一空白。
  • 除非你是 Microsoft 生态的用户，否则你可能并不关心这一点。
• 审计日志流（2024）
  • 使用 grist-core 会记录大量有用的信息，但并未专门针对审计进行组织。审计日志流提供了这种组织方式，以及用于设置的用户界面。
  • 企业可能会关心这一点。
• 高级管理控制（2025）
  • 这是供 Grist 安装管理员监控和编辑用户对资源访问权限的专用页面。
  • 它使用了一组 grist-core 中不存在的专用管理端点。
  • 如果你要运行一个大型 Grist 安装，且有员工来来去去，你可能会关心这一点。
• Grist 助手（2025）
  • grist-core 中有一个 AI 公式助手——仅限于处理公式——但更新的助手可以帮助完成更广泛的任务，例如构建表格和仪表板、设计样式和格式、解释访问规则以及修改数据。
  • 如果你有很多用户需要帮助构建文档或处理数据，你可能会关心这一个。
• 邀请通知（2025）
  • 当用户被添加到文档、工作区或站点时，通过电子邮件通知，他们会收到一封包含访问该资源链接的电子邮件。
  • 这个链接并不特殊，使用 grist-core，你可以自己或让同事直接发送链接。
  • 对于用户之间沟通不密切的大型 Grist 安装，电子邮件可能不错？很难猜测你是否会关心这一个。
• 文档变更和评论通知（2025）
  • 你可以使用 webhook 在 grist-core 中实现变更通知，但不太方便。
  • 人们多年来一直要求这个功能。如果你需要借口让老板为 Grist 付费，这可能终于是一个可行的理由？
• 自动化（2026）
  • 一种供文档所有者构建触发器驱动工作流的工具：在任何表上设置条件，然后在行匹配时发送电子邮件（支持动态收件人和 Markdown）或触发 webhook，并在投递日志中查看结果。
  • 你可以在 grist-core 中使用 webhook 构建类似的流程，但你需要自己搭建电子邮件部分和监控。
• OAuth 应用（2026）
  • 注册和授权 OAuth 应用，将其范围限定到特定的组织、工作区或文档，并在之后审查或撤销该访问权限。
  • 一种让外部工具连接到 Grist 的方式，具有限定范围、可撤销的访问权限，而不是交出完整的 API 密钥。如果你要将 Grist 连接到其他软件，你可能关心这一点，作为 API 密钥的替代方案。
• MCP 服务（2026）
  • 一个内置的 Model Context Protocol 端点，让 Claude 或 ChatGPT 等 AI 客户端可以通过 JSON-RPC 读取和编辑 Grist 文档。通过 GRIST_MCP_ENABLED 启用（参见环境变量）。
  • 使用 grist-core，你仍然可以使用众多通过其 REST API 与 Grist 通信的社区 MCP 服务之一。内置服务为你省去了这项工作。
• 通过 OIDC 或 SAML 实现单点登录（SSO）（2026）

使用 Grist

要使用 Docker 在你的计算机上运行默认版本的 grist-core，请执行：

docker pull gristlabs/grist
docker run -p 8484:8484 -it gristlabs/grist

然后在浏览器中访问 http://localhost:8484。

在全新安装时，你会看到一个 快速设置 页面，它会引导你选择管理员邮箱、选择用户登录方式，并设置谁可以使用该站点。要跳过第一个屏幕，请在容器的启动日志中查找包含生成的启动密钥的行，并在提示时粘贴它。一旦你在快速设置结束时点击 应用并上线！，该站点就正式开放，你将能够创建、编辑、导入和导出文档。这里有分步指南：首次运行设置。

如果你更想完全跳过快速设置，并以开放的单用户设置开始，请设置 GRIST_IN_SERVICE=true。你之后可以从 管理面板 返回相同的设置。

要在多次 docker 运行之间保留你的工作，请将一个目录共享为 /persist：

docker run -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist

在 templates.getgrist.com 获取用于工资单、库存管理、发票、D&D 遭遇追踪等的模板，或使用你在 docs.getgrist.com 上创建的任何文档。

如果你需要更改 Grist 运行的端口，请设置 PORT 变量，而不要只是更改端口映射：

docker run --env PORT=9999 -p 9999:9999 -v $PWD/persist:/persist -it gristlabs/grist

要启用 gVisor 沙箱，请设置 --env GRIST_SANDBOX_FLAVOR=gvisor。这应该适用于默认 docker 设置，但可能不适用于所有环境。

你可以在我们的 自管理 Grist 文档中找到更多关于配置 Grist、设置身份验证以及在公共服务器上运行它的信息。

将 Grist 与 OpenRouter 一起使用，以实现模型无关和 Claude 支持

（说明由 @lshalon 贡献）

Grist 的 AI Formula Assistant 可以配置为使用 OpenRouter，而不是直接连接到 OpenAI，这使你能够访问包括 Anthropic 的 Claude 模型在内的各种 AI 模型。这并不是使用 Claude 模型的唯一方式，但如果你想在 Grist 中使用 Claude 模型，或打算使用其他更便宜、更快或可能更新的模型，这是一个不错的选择。因为这种配置让你在选择最适合公式生成需求的 AI 模型时拥有更大的灵活性。 要设置 OpenRouter 集成，请配置以下环境变量：

必需：将端点设置为 OpenRouter 的 API

ASSISTANT_CHAT_COMPLETION_ENDPOINT=https://openrouter.ai/api/v1/chat/completions

必需：你的 OpenRouter API 密钥

ASSISTANT_API_KEY=your_openrouter_api_key_here

在 https://openrouter.ai/ 注册 OpenRouter API 密钥

可选：指定要使用的模型（示例如下）

ASSISTANT_MODEL=anthropic/claude-3.7-sonnet

或其他选项，例如

ASSISTANT_MODEL=deepseek/deepseek-r1-zero:free

ASSISTANT_MODEL=qwen/qwq-32b:free

ASSISTANT_MODEL=mistralai/mistral-saba

可选：为回退设置更大的上下文模型

ASSISTANT_LONGER_CONTEXT_MODEL=anthropic/claude-3-opus-20240229

使用此配置，Grist 的 AI Formula Assistant 将通过 OpenRouter 将请求路由到你指定的模型。这使你能够：

访问 Anthropic 的 Claude 模型，这些模型擅长理解上下文并生成准确的公式 在不更改 Grist 配置的情况下在不同 AI 模型之间切换 利用 OpenRouter 的路由能力，以优化成本、速度或质量

你可以在 OpenRouter 网站上找到可用模型及其标识符。 注意：使用 OpenRouter 时，请确保不要设置 OPENAI_API_KEY 变量，因为这会覆盖 OpenRouter 配置。

可用的 Docker 镜像

默认 Docker 镜像为 gristlabs/grist。它包含 Grist 社区版的全部功能，以及 Grist 完整版的额外扩展。这些扩展不采用自由或开源许可证。仅当在管理面板中将版本设置为 “Full Grist” 时，这些扩展才会激活；当设置为 “Community Grist” 时，它们处于惰性且未激活状态。

如果你更愿意使用仅包含自由和开源代码的镜像，可以使用 gristlabs/grist-oss Docker 镜像。它在功能上等同于将版本设置为 “Community Grist” 的 gristlabs/grist 镜像。

管理面板

管理面板用于检查并调整你的安装：检查健康探测、更改一些设置、切换功能。访问 Grist 服务器上的 /admin 即可找到它。如果你尚未以安装管理员身份登录，面板会提示你进行启动密钥登录，然后你可以在那里粘贴该密钥。

新安装会自动生成启动密钥，并在启动时将其打印到容器日志中。请留意类似下面的一行：

BOOT KEY: <random-string>

如果你更愿意自行选择启动密钥，请设置 GRIST_BOOT_KEY：

docker run -p 8484:8484 -e GRIST_BOOT_KEY=secret -it gristlabs/grist

该面板会收集常见问题的探测项。如果你遇到未覆盖的问题，请在 BootProbes 中添加一个探测项，或提交 issue，以便其他人处理。

从源码构建

要从源码构建 Grist，请按照以下步骤操作：

yarn install
yarn install:python
yarn build
yarn start
# Grist will be available at http://localhost:8484/

默认情况下，构建的是完整版：yarn install 会下载可选扩展（到 ext 目录中），这些扩展只有在从管理面板切换到 Grist 完整版时才会启用。请注意，这会将非 OSS 代码添加到你的构建中。

如果你希望在构建中跳过包含扩展，步骤如下：

yarn run set-community-edition
yarn install:python
yarn build
yarn start
# Grist will be available at http://localhost:8484/

你可以在管理面板中在 Grist 完整版和社区版之间切换。

首次启动 Grist 时，它会像全新的 Docker 安装一样显示快速设置页面。请在运行 yarn start 的终端中查看启动密钥。如果你想在开发调试时跳过快速设置，请使用 GRIST_IN_SERVICE=true 运行。

文档中的 Grist 公式将使用直接在你的机器上执行的 Python 运行。你可以使用 GRIST_SANDBOX_FLAVOR 环境变量配置沙箱。

• 在 macOS 上，export GRIST_SANDBOX_FLAVOR=macSandboxExec 使用原生 sandbox-exec 命令进行沙箱隔离。
• 在安装了 gVisor 的 runsc 的 Linux 上，可以选择 export GRIST_SANDBOX_FLAVOR=gvisor。
• 在任何操作系统上（包括 Windows），都可以使用 export GRIST_SANDBOX_FLAVOR=pyodide。

这些沙箱方法是为我们在 Grist Labs 自身使用而编写的，在你的环境中可能需要调整才能工作——非常欢迎在此提交 pull request！

登录

与 git 类似，Grist 具备跟踪文档修订历史的功能。因此，为了完整运行，Grist 需要知道修改文档的用户是谁。在此之前，它会以受限的匿名模式运行。

设置登录最便捷的方式是全新安装时出现的快速设置页面。它让你从简短的菜单中选择管理员邮箱和身份验证方式。完整操作步骤请参见首次运行设置。之后你可以随时从管理面板重新访问这些相同的设置。

如果你完全不想配置登录，可以以单一默认身份运行。设置 GRIST_DEFAULT_EMAIL，"登录"按钮就会将你的操作归属到该地址：

docker run --env GRIST_DEFAULT_EMAIL=my@email -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist

你可以在用户菜单的 Profile Settings 中更改你的名字。

对于多用户运行，或者如果你希望通过公共互联网访问 Grist，你需要将其连接到单点登录服务。使用 getgrist.com 登录和转发身份验证在所有版本中均可用；通过 OIDC 或 SAML 直接连接到你自己的身份提供商，需使用激活密钥，且完全受支持。Grist 已通过 Authentik、Auth0 以及通过 Dex 使用 Google/Microsoft 登录进行了测试。

翻译

我们使用 Weblate 来管理翻译。感谢所有参与贡献的人。特别感谢 ANCT 的开发者们，他们付出了艰苦的努力，使应用程序的很大一部分得以本地化。Merci beaucoup！

为什么选择自由和开源软件？

本仓库 grist-core 由 Grist Labs 维护。我们在 getgrist.com 上提供的旗舰产品正是由你在这里看到的代码构建而成，并结合了为支持大量用户、处理计费等而设计的业务专用软件。

Grist Labs 是一家开放核心（open-core）公司。我们以服务形式提供 Grist 托管，包含免费和付费方案。我们还开发并销售与 Grist 相关的专有许可功能，面向拥有大型自管理安装的企业需求。

我们将数据可移植性和自主权视为核心价值，而 grist-core 是其中不可或缺的一部分。我们致力于维护和改进 grist-core 代码库，并审慎考虑专有产品如何影响数据可移植性和自主权。

通过开放其源代码并提供经 OSI 认可的免费许可证，Grist 让其用户受益：

• 开发者社区。 对于一个通用的类电子表格产品而言，检查源代码、修复 bug 和开发新功能的自由至关重要，因为总有各种各样对某些人至关重要的长尾功能。
• 增强信任。 因为任何人都可以检查源代码，“通过隐匿实现安全”不是一个选项。代码中的漏洞可以被他人发现并在造成损害之前报告。
• 独立性。 无论 Grist Labs 业务兴衰如何，Grist 都可供你使用，因为它是开源的，并且可以自托管。使用我们的托管方案很方便，但你不会被锁定。
• 价格灵活性。 如果你资金紧张但有时间投入，自托管是一个很好的选择。而 DIY 用户可能具备深入其中并进行改进的技术能力和动力，这可以让所有 Grist 用户受益。
• 可扩展性。 对开发者而言，源代码开放使得构建扩展（例如 自定义小部件）更加容易。你可以更轻松地将 Grist 纳入你的流水线。如果缺少某个功能，你可以直接获取源代码并在其基础上构建。

有关 Grist Labs 的历史和原则的更多信息，请参阅我们的关于我们页面。

赞助商

评价

• ProductHunt 上的 Grist
• AppSumo 上的 Grist（终身优惠已售罄）
• Capterra、G2、TrustRadius

环境变量

Grist 可以通过多种方式进行配置。以下是它主要敏感的环境变量：

变量	用途
ALLOWED_WEBHOOK_DOMAINS	允许在 webhook 中使用的域名列表，以逗号分隔（例如 webhook.site,zapier.com）。你可以将其设置为 * 以允许所有域名，但若这样做，如果你不完全信任用户，我们建议使用经过精心锁定配置的代理（参见 GRIST_PROXY_FOR_UNTRUSTED_URLS）。否则，你内部网络上的服务可能会面临被操纵的风险。
APP_DOC_URL	浏览器访问此 doc worker 时应使用的 URL。在多服务器部署中，如果不使用 GRIST_FLEET，则每个 doc worker 都必须能通过其各自独有的公共 URL 被浏览器访问到。如果不使用 GRIST_ROUTER_URL 来自动分配这些 URL，那么在实践中就需要设置 APP_DOC_URL。无论在哪里设置，它对每个 worker 都必须各不相同，因为客户端正是通过它来访问持有文档的 worker；而在 APP_DOC_INTERNAL_URL 未设置时，其他服务器也通过它来访问该 worker。在单一前端之后，这意味着每个 worker 对应一个路径，例如 https://grist.example.com/dw/worker-1。与 GRIST_FLEET 一起设置时会在启动时被拒绝，因为集群会将客户端路由到它们所访问的任意服务器，而绝不会使用它。
APP_DOC_INTERNAL_URL	类似 APP_DOC_URL，但供其他服务器通过内部域名解析（例如在 docker 环境中）访问此服务器时使用。仅在 doc worker 中定义此值才有意义。默认为 APP_DOC_URL。如果两者都未设置，则会根据 GRIST_HOST，或根据此服务器访问 Redis 所用的接口推导出一个地址。共享同一主机的 worker 可以通过路径加以区分，从此 URL 推导出的 id 中会包含该路径。
APP_HOME_URL	home api 的 URL 前缀（home 和 doc 服务器都需要此项）
APP_HOME_INTERNAL_URL	类似 APP_HOME_URL，但供 home 和 doc 服务器通过内部域名解析（例如在 docker 环境中）访问任意 home worker 时使用。默认为 APP_HOME_URL
APP_STATIC_URL	静态资源的 URL 前缀
APP_STATIC_INCLUDE_CUSTOM_CSS	设置为 "true" 以在静态页面中包含 custom.css（来自 APP_STATIC_URL）
APP_UNTRUSTED_URL	提供/预期插件内容的 URL。
GRIST_ACTION_HISTORY_MAX_ROWS	在修剪之前 ActionHistory 中允许的最大行数（最多可有 1.25 的宽限系数）。默认为 1000。⚠️ 值过低可能会导致“基于副本工作”功能出现故障
GRIST_ACTION_HISTORY_MAX_BYTES	在修剪之前 ActionHistory 中允许的最大字节数（最多可有 1.25 的宽限系数）。默认为 1Gb。⚠️ 值过低可能会导致“基于副本工作”功能出现故障
GRIST_ADAPT_DOMAIN	设置为 "true" 以支持多个基础域名（注意，host header 应当可信）
GRIST_ALLOW_AUTOMATIC_VERSION_CHECKING	是否允许 Grist 自动检查是否有更新的 Grist 版本可用。在默认的 grist 和 grist-ee Docker 镜像中默认为 "true"。在 grist-oss 及其他所有环境中默认为 false。
GRIST_ALLOW_DEPRECATED_BARE_ORG_DELETE	如果设置，则弃用的 DELETE /api/orgs/:orgId 端点将可用。
GRIST_APP_ROOT	包含 Grist sandbox 和 assets 的目录（具体为 sandbox 和 static 子目录）。
GRIST_ATTACHMENTS_THRESHOLD_MB	每个文档的附件存储上限，超过该值后 Grist 将推荐使用外部存储（如果可用）。默认为 50MB。
GRIST_BACKUP_DELAY_SECS	文档更改后等待这么久再进行备份
GRIST_BOOT_KEY	如果设置，则使用此密钥在 /boot 以安装管理员身份登录。新安装会自动生成一个密钥并在启动时打印；仅当你想要自己选择密钥时才设置此项。
GRIST_BROADCAST_TIMEOUT_MS	设置 Web 客户端在接受关于某文档的广播消息时所允许的最长时间，超过则断开连接（默认：1 分钟）。
GRIST_DATA_DIR	存储文档的目录。默认为相对于 Grist 应用目录的 docs/。在 Grist 的默认 Docker 镜像中，其默认值为 /persist/docs，以便作为挂载卷使用。
GRIST_DEFAULT_EMAIL	如果设置，在未提供其他凭据时以此用户身份登录
GRIST_DEFAULT_PRODUCT	如果设置，这将控制新站点启用的功能和限制。参见 Product.ts 中的 PRODUCTS 名称。
GRIST_DEFAULT_LOCALE	当 Grist 无法遵循浏览器区域设置时用作回退的区域设置。默认为 en-US。应匹配 app/common/LocaleCodes.ts 中的区域代码。
GRIST_DOC_WORKER_ID	一个 doc worker 的标识，对于共享同一 Redis 的每台服务器都必须各不相同。将其留空则会自动推导出一个。两台服务器共享同一个值可能会同时打开同一文档。
GRIST_DOMAIN	在托管版 Grist 中，Grist 从该域名的子域名提供服务。默认为 "getgrist.com"。
GRIST_EDITION	选择 yarn install 钩子设置哪个版本，full 或 community。优先于 yarn run set-full-edition / yarn run set-community-edition 写入的 grist-edition 文件。默认为 full。参见从源码构建。
GRIST_SKIP_EXT_AUTOSETUP	设置为 1 以跳过下载完整版 ext 材料的 yarn install 钩子。在通过其他方式安装扩展的环境中很有用（Docker 构建、grist-desktop、grist-static）。参见从源码构建。
GRIST_EXPERIMENTAL_PLUGINS	启用实验性插件
GRIST_EXTERNAL_ATTACHMENTS_MODE	启用附件外部存储所必需。设置为 "snapshots" 以启用外部存储。默认值为 "none"。请注意，启用时还必须配置快照存储。
GRIST_ENABLE_SERVICE_ACCOUNTS	启用 service accounts 功能。该功能允许用户创建特殊的服务账号，他们可以管理这些账号，并授予其对选定资源的受限访问权限。这是一种为第三方自动化获取细粒度 api key 的有用方式。默认未设置
GRIST_ENABLE_REQUEST_FUNCTION	启用 REQUEST 函数。该函数以类似于 requests.request 的方式执行 HTTP 请求。此函数带来显著的安全风险，因为当 Grist 可公开访问时，它可能让用户调用内部端点。此函数还可能导致性能问题。默认未设置。
GRIST_HEADERS_TIMEOUT_MS	如果设置，则覆盖 node 的 server.headersTimeout 标志。
GRIST_HIDE_UI_ELEMENTS	要禁用的 UI 功能列表，以逗号分隔。允许的部分名称：helpCenter、billing、templates、createSite、multiSite、multiAccounts、importFromAirtable、sendToDrive、tutorials、supportGrist、themes、automations。如果某部分同时也存在于 GRIST_UI_FEATURES 中，它仍将被禁用。
GRIST_HOST	在端口上监听时使用的主机名。它也决定 doc worker 向其同伴发布的地址，以及由此推导出的标识：将其设置为 0.0.0.0 以在所有接口上监听，留空则仅在 localhost 上监听。
GRIST_PROXY_FOR_UNTRUSTED_URLS	用于投递 webhook 载荷的代理完整 URL。默认值为 direct，表示不通过代理投递载荷。
HTTPS_PROXY 或 https_proxy	用于获取自定义 widget 仓库或从颁发者获取 OIDC 配置的反向 Web 代理（企业代理）的完整 URL。
GRIST_ID_PREFIX	对于形如 o-* 的子域名，预期或生成 o-${GRIST_ID_PREFIX}*。
GRIST_IGNORE_SESSION	如果设置，Grist 将不使用会话进行身份验证。
GRIST_INCLUDE_CUSTOM_SCRIPT_URL	如果设置，将在所有应用页面的 <script> 标签中加载所引用的 URL。
GRIST_IN_SERVICE	如果为 "true"，则跳过首次运行的快速设置关卡，让服务器直接进入服务状态。新安装默认为 "false"，以便操作员完成快速设置；现有安装默认为 "true"。
GRIST_INST_DIR	Grist 服务器的 Grist 实例配置文件路径。
GRIST_KEEP_ALIVE_TIMEOUT_MS	如果设置，则覆盖 node 的 server.keepAliveTimeout 标志。
GRIST_LIST_PUBLIC_SITES	如果设置为 true，则向匿名用户列出与公众共享的站点。默认为 false。
GRIST_MANAGED_WORKERS	如果设置，Grist 可以假定：如果针对某 doc worker 的 URL 返回 404，则该 worker 已不存在
GRIST_MAX_NEW_USER_INVITES_PER_ORG	如果设置，则限制每个组织邀请新用户的数量。一旦超出，额外的邀请将被阻止，直到被邀请用户首次登录或被取消邀请
GRIST_MAX_BILLING_MANAGERS_PER_ORG	如果设置，则限制每个组织的账单管理员数量
GRIST_MAX_PARALLEL_REQUESTS_PER_DOC	每个文档允许的并发 API 请求最大数量（默认为 10，设置为 0 表示不限）
GRIST_MAX_UPLOAD_ATTACHMENT_MB	附件允许的最大大小（0 或留空表示不限）。
GRIST_MAX_UPLOAD_IMPORT_MB	导入（.grist 文件除外）允许的最大大小（0 或留空表示不限）。
GRIST_ACTIVEDOC_TIMEOUT_SECONDS	文档在没有任何客户端的情况下保持打开的秒数，超过后即关闭。当设置了 NODE_ENV=production 时默认为 30s，否则为 5s。
GRIST_OFFER_ALL_LANGUAGES	如果设置，则向用户提供所有已翻译的语言（默认情况下，仅向用户提供设置了特殊 'good enough' 键的语言）。
GRIST_ORG_IN_PATH	如果为 true，则将组织编码在路径中而非域名中
GRIST_PAGE_TITLE_SUFFIX	追加到 HTML 文档 <title> 末尾的字符串。默认为 " - Grist"。设置为 _blank 表示完全不添加后缀。
GRIST_PROXY_AUTH_HEADER	已弃用，被解释为 GRIST_FORWARD_AUTH_HEADER 的同义词。
GRIST_REQUEST_TIMEOUT_MS	如果设置，则覆盖 node 的 server.requestTimeout 标志。
GRIST_RESTART_SHELL	设置为 "true"/"false" 以启用/禁用就地重启，从而在不丢弃监听套接字的情况下应用配置更改。在 Node 下的 Linux 上默认开启，在 Windows 和 Electron 上关闭。
GRIST_ROUTER_URL	可选，用于向负载均衡器（取消）注册服务器的 api 的 URL
GRIST_SERVE_SAME_ORIGIN	设置为 "true" 以在与顶层页面相同的协议-主机-端口上访问 home 服务器和 doc worker，与自定义域名的情况相同（注意，host header 应当可信）
GRIST_SERVERS	要设置的服务器类型。以逗号分隔的值，可包含 "home"、"docs"、"static" 和/或 "app"。默认为 "home,docs,static"。
GRIST_SESSION_COOKIE	如果设置，则覆盖 Grist 的 cookie 名称
GRIST_SESSION_DOMAIN	如果设置，则将该 cookie 与给定域名关联 - 否则默认为 GRIST_DOMAIN
GRIST_SESSION_SECRET	用于编码会话的密钥
GRIST_SQLITE_MODE	如果设置为 wal，则以 WAL 模式使用 SQLite；如果设置为 sync，则以 SYNCHRONOUS=full 使用 SQLite；如果设置为 nosync（默认值），则以 SYNCHRONOUS=off 使用 SQLite
GRIST_ANON_PLAYGROUND	当设置为 false 时，拒绝匿名用户访问主页（但文档仍可共享给匿名用户）。默认为 true，除非 GRIST_ORG_CREATION_ANYONE 为 false。
GRIST_FORCE_LOGIN	将其设置为 true 类似于设置 GRIST_ANON_PLAYGROUND: false，但它会阻止任何匿名访问（因此任何公开共享的文档实际上都要求用户在查看之前通过身份验证）
GRIST_PERSONAL_ORGS	当设置为 false 时，阻止在用户注册时创建新的个人组织。默认为 true，除非 GRIST_ORG_CREATION_ANYONE 为 false。
GRIST_ORG_CREATION_ANYONE	当设置为 false 时，阻止非管理员用户创建新的团队组织。将 GRIST_ANON_PLAYGROUND 和 GRIST_PERSONAL_ORGS 的默认值设为 false。默认为 true。
GRIST_SINGLE_ORG	设置为某个组织的 "domain" 以将客户端固定到该组织
GRIST_TEMPLATE_ORG	设置为某个组织的 "domain" 以显示来自该组织的公开文档
GRIST_HELP_CENTER	设置帮助中心链接引用
GRIST_TERMS_OF_SERVICE_URL	如果设置，则添加服务条款链接
GRIST_CONTACT_SUPPORT_URL	设置错误页面上联系支持的链接（例如：电子邮件地址或在线表单）
GRIST_ONBOARDING_VIDEO_ID	设置主页和入门引导中显示的 YouTube 视频 ID
GRIST_CUSTOM_COMMON_URLS	覆盖默认的 commons URL。其值应为一个 JSON 对象，且是 ICommonUrls 接口的子集。
GRIST_SUPPORT_ANON	如果设置为 'true'，则显示匿名访问的 UI（默认不显示）
GRIST_SUPPORT_EMAIL	如果设置，则授予具有指定电子邮件的用户支持权限。主要的额外权限是能够以列出方式与所有用户共享站点、工作区和文档。
GRIST_OPEN_GRAPH_PREVIEW_IMAGE	在社交媒体或聊天应用等网站上分享链接时的预览图片 URL。
GRIST_TELEMETRY_LEVEL	遥测级别。可设置为：off（默认）、limited 或 full。
GRIST_THROTTLE_CPU	如果设置，则启用 CPU 节流
GRIST_TRUST_PLUGINS	如果设置，则预期插件从与 Grist 应用其余部分相同的主机提供服务，而非从不同主机提供服务。通常，插件从不同主机提供服务，以便 Grist 应用使用的 cookie 不会自动对其可用。仅当你理解其安全影响时才启用此项。
GRIST_USER_ROOT	用于查找插件的额外路径 - Grist 将在 $GRIST_USER_ROOT/plugins 中扫描插件。
GRIST_UI_FEATURES	要启用的 UI 功能列表，以逗号分隔。允许的部分名称：helpCenter、billing、templates、createSite、multiSite、multiAccounts、importFromAirtable、sendToDrive、tutorials、supportGrist、themes、automations。如果某部分同时也存在于 GRIST_HIDE_UI_ELEMENTS 中，则不会启用。注意：importFromAirtable 和 automations 即使未在此处列出也默认启用；请使用 GRIST_HIDE_UI_ELEMENTS 来禁用它们。
GRIST_UNTRUSTED_PORT	如果设置，插件将从给定端口提供服务。这是设置 APP_UNTRUSTED_URL 的替代方案。
GRIST_VACUUM_ON_CLOSE	当设置为 false 时，不在文档因不活跃而关闭时对其进行压缩。只有在有足够空间可回收、值得付出存储结果的代价时，文档才会被压缩。默认为 true。
GRIST_WIDGET_LIST_URL	指向 widget 清单的 URL，默认使用 https://github.com/gristlabs/grist-widget/releases/download/latest/manifest.json
GRIST_LOG_LEVEL	输出的日志消息最低级别：error、warn、info 或 debug。默认为 info。
GRIST_LOG_HTTP	当设置为 true 时，记录 HTTP 请求和响应信息。默认为 false。
GRIST_LOG_HTTP_BODY	当设置为 true 时，记录带有 API 错误的请求体。如果 GRIST_LOG_HTTP 也为 true，则记录所有 HTTP 请求的请求体。:warning: 请注意，这可能会在日志中泄露机密信息。:warning: 默认为 false。
GRIST_LOG_AS_JSON	当此变量设置为 true 或真值时，以 JSON 而非纯文本格式输出日志行。
GRIST_LOG_API_DETAILS	当此变量设置为 true 或真值时，记录 API 调用详情。
COOKIE_MAX_AGE	会话 cookie 的最大存活时间，默认为 90 天；可设置为 "none" 使其成为会话 cookie
HOME_PORT	REST API 服务器要监听的端口号；如果设置为 "share"，则将 API 端点添加到常规 grist 端口。
PORT	Grist 服务器要监听的端口号
REDIS_URL	可选的 redis 服务器，用于浏览器会话和数据库查询缓存
GRIST_SNAPSHOT_TIME_CAP	可选。定义跟踪桶的上限。用法：{"hour": 25, "day": 32, "isoWeek": 12, "month": 96, "year": 1000}
GRIST_SNAPSHOT_KEEP	可选。为某文档无条件保留的近期快照数量，无论它们是在何时创建的
GRIST_PROMCLIENT_PORT	可选。如果设置，则在指定端口号上提供 Prometheus 指标。⚠️ 请确保使用不公开暴露的端口 ⚠️。
GRIST_ENABLE_SCIM	可选。如果设置，则启用 SCIM API 端点（实验性）
GRIST_OIDC_...	可选。用于配置 OpenID 身份验证的环境变量。完整相关环境变量列表请参见 OpenID Connect 文档。另见登录。
GRIST_SAML_...	可选。用于配置 SAML 身份验证的环境变量。完整相关环境变量列表请参见 SAML 文档。另见登录。
GRIST_IDP_EXTRA_PROPS	可选。如果设置，则定义你的身份提供方返回的哪些额外字段将存储在 home 数据库的 users 表（options.ssoExtraInfo 对象）中。用法：'onekey,anotherkey'。
GRIST_FEATURE_FORM_FRAMING	可选。配置出于安全原因添加在已渲染表单周围的边框；可设置为：border 或 minimal。默认为 border。
GRIST_TRUTHY_VALUES	可选。除英文默认值外，数据引擎应视为真值的额外单词列表，以逗号分隔。例如："oui,ja,si"
GRIST_FALSY_VALUES	可选。除英文默认值外，数据引擎应视为假值的额外单词列表，以逗号分隔。例如："non,nein,no"
GRIST_ENABLE_USER_PRESENCE	可选，默认启用。如果设置为 'false'，则禁用所有用户在线状态功能。

完整版功能开关：

部分功能位于 Grist 的完整版中，而非 grist-core。其功能开关列在此处供参考；仅当完整版被构建并启用时才会生效（参见从源代码构建）。

变量	用途
GRIST_ACTIVATION	完整版的激活密钥，直接提供而非通过管理面板。适用于脚本化或无头部署。优先于 GRIST_ACTIVATION_FILE。
GRIST_ACTIVATION_FILE	包含激活密钥的文件路径，在未设置 GRIST_ACTIVATION 时读取。
GRIST_MCP_ENABLED	若设为 "true"，则启用 MCP 服务，使 Claude 等外部客户端能够通过 JSON-RPC 与 Grist 通信。默认为 "false"。
GRIST_ENABLE_OIDC_SERVER	若设为 "true"，则启用 Grist 的 OAuth / OIDC 服务，该服务签发 OAuth 应用和 MCP 客户端用于身份验证的令牌。默认为 "false"。
GRIST_ENABLE_OIDC_DCR	若设为 "true"，则启用 OAuth 动态客户端注册（RFC 7591）：提供 POST /oidc/reg 并在发现文档中公布它，使 OAuth 和 MCP 客户端无需预先配置即可注册。默认为 "false"。
GRIST_OIDC_DCR_RATE_LIMIT	未认证的 POST /oidc/reg 端点每分钟允许的请求数。默认为 60。
GRIST_OIDC_CIMD_ALLOWED_HOSTS	逗号分隔的主机允许列表，允许获取这些主机的客户端 ID 元数据文档（CIMD），使客户端可以通过 HTTPS 元数据 URL 标识自身，而无需预先注册。为空（默认值）则禁用 CIMD。* 允许任何主机，仅应与 GRIST_PROXY_FOR_UNTRUSTED_URLS 一起使用。

AI 公式助手相关变量（均为可选）：

变量	用途
ASSISTANT_API_KEY	可选。向外部 AI 对话端点发出请求时传递的 API 密钥。
ASSISTANT_CHAT_COMPLETION_ENDPOINT	可选。要调用的聊天补全风格端点。若使用 OpenAI 则无需设置。
ASSISTANT_MODEL	可选。若设置，该字符串会在对 AI 对话端点的调用中传递。
ASSISTANT_LONGER_CONTEXT_MODEL	可选。若设置，因上下文长度限制而失败的请求将使用此模型设置重试。
OPENAI_API_KEY	可选。ASSISTANT_API_KEY 的同义词，假定使用的是 OpenAI 端点。在 OpenAI 上注册账户，然后在此处生成密钥。

在撰写本文时，已知 AI 助手可用于 OpenAI 聊天补全端点（即以 /v1/chat/completions 结尾的端点）。 已知它也可用于 llama-cpp-python 和 LM Studio 提供的聊天补全端点。为获得有用的结果，大模型应与 GPT 3.5 或更高版本相当。

沙箱相关变量：

变量	用途	沙箱
GRIST_SANDBOX_FLAVOR	可以是 gvisor、pynbox、unsandboxed、docker 或 macSandboxExec。若设置，强制 Grist 使用指定类型的沙箱。	不适用
GRIST_SANDBOX	作为沙箱运行的程序或镜像名称。技术细节参见 NSandbox.ts。	不适用
GVISOR_LIMIT_NPROC	在 Linux 上运行时沙箱允许生成的现存进程数。默认为 8。	GVisor
GVISOR_LIMIT_MEMORY	沙箱进程虚拟内存的最大大小（以字节为单位）。默认无限制。	GVisor

转发认证变量：

变量	用途
GRIST_FORWARD_AUTH_HEADER	如果设置，则信任指定的请求头（例如 "x-forwarded-user"）包含已授权用户的电子邮件，并启用 "forward auth" 登录。
GRIST_FORWARD_AUTH_LOGIN_PATH	如果设置了 GRIST_FORWARD_AUTH_HEADER，Grist 将在此路径监听登录。默认为 /auth/login。
GRIST_FORWARD_AUTH_LOGOUT_PATH	如果设置了 GRIST_FORWARD_AUTH_HEADER，当用户注销时，Grist 将转发到此路径。

转发认证支持两种模式，通过 GRIST_IGNORE_SESSION 区分：

1. 使用会话，并在登录端点启用转发认证。

   例如，使用 traefik 反向代理和 traefik-forward-auth 中间件：

   • GRIST_IGNORE_SESSION：不要设置，或设置为假值。
   • 确保你的反向代理将转发认证中间件应用于 GRIST_FORWARD_AUTH_LOGIN_PATH 和 GRIST_FORWARD_AUTH_LOGOUT_PATH。
   • 如果你希望在某些情况下允许匿名访问，请确保所有其他路径不受 转发认证中间件影响。Grist 会在需要时通过重定向到 GRIST_FORWARD_AUTH_LOGIN_PATH 来触发它。一旦用户登录，Grist 将使用会话 识别用户，直到注销。

2. 不使用会话，并在所有端点启用转发认证。

   例如，使用 HTTP Basic Auth 和服务器配置，将请求头（在 GRIST_FORWARD_AUTH_HEADER 中指定）设置为已登录用户。

• GRIST_IGNORE_SESSION：设置为 true。将不使用 Grist 会话。
• 确保你的反向代理为所有可能需要 登录信息的请求设置你指定的请求头。这个请求头绝不能 被用户伪造，因为 Grist 会信任其中的任何内容。

使用转发认证时，你可能还希望设置以下变量：

• GRIST_FORCE_LOGIN=true 以禁用匿名访问。

插件：

Grist 有一个内部使用的插件系统。你可以用它做的一件有用的事 是在 Grist 构建中包含自定义小部件。自定义小部件 通常只需设置 GRIST_WIDGET_LIST_URL 即可提供， 但这样做的缺点是属于外部依赖，这对于离线使用或归档 可能很不方便。插件提供了一种替代方案。

要将自定义小部件作为插件“打包”：

• 添加 plugins 的子目录，例如 plugins/my-widgets。 或者，你可以将 GRIST_USER_ROOT 环境 变量设置为任何你想要的路径，然后在该路径中创建 plugins/my-widgets。
• 在该子目录中添加一个看起来像 这样的 manifest.yml 文件：

name: My Widgets
components:
  widgets: widgets.json

• widgets.json 文件应采用 grist-widget 仓库生成的格式，并应与 manifest.yml 放在同一目录中。plugins/my-widgets 中的任何材料 都将由 Grist 提供，并且可以在 widgets.json 中使用相对 URL。
• 所有文件就位后，重启 Grist。你的小部件现在 应该会出现在自定义小部件下拉菜单中，与 来自 GRIST_WIDGET_LIST_URL 的任何其他小部件一起提供。
• 如果愿意，你可以添加多个插件子目录，包含 多组小部件，它们都将可用。

Google Drive 集成：

变量	用途
GOOGLE_CLIENT_ID	设置为与 Google API 客户端一起使用的 Google Client Id
GOOGLE_CLIENT_SECRET	设置为与 Google API 客户端一起使用的 Google Client Secret
GOOGLE_API_KEY	设置为与 Google API 客户端一起使用的 Google API Key（访问公共文件）
GOOGLE_DRIVE_SCOPE	设置为 Google Drive 集成请求的作用域（默认为 drive.file）

数据库变量：

变量	用途
TYPEORM_DATABASE	sqlite 的数据库文件名，或其他数据库类型的数据库名称
TYPEORM_HOST	数据库主机
TYPEORM_LOGGING	设置为 'true' 可查看所有 sql 查询
TYPEORM_PASSWORD	使用的密码
TYPEORM_PORT	数据库端口号（如果不是该数据库类型的默认值）
TYPEORM_TYPE	设置为 'sqlite' 或 'postgres'
TYPEORM_USERNAME	连接使用的用户名
TYPEORM_EXTRA	以 JSON 格式传递给 TypeORM 的任何其他属性

仅 Docker 变量：

变量	用途
GRIST_DOCKER_USER	可选。当容器以 root 用户运行时，Grist 服务以此用户身份运行。覆盖默认值。
GRIST_DOCKER_GROUP	可选。当容器以 root 用户运行时，Grist 服务以此用户组身份运行。覆盖默认值。

测试：

变量	用途
GRIST_TESTING_SOCKET	仅在测试期间用于带外通信的套接字。
GRIST_TEST_FORCE_LIGHT_MODE	如果设置，Grist 将使用浅色模式，即使系统偏好为深色。某些测试只是假定为浅色模式。
GRIST_TEST_HTTPS_OFFSET	如果设置，则在指定偏移量处添加 https 端口。这在测试中很有用。
GRIST_TEST_SSL_CERT	如果设置，包含 SSL 证书的文件名。
GRIST_TEST_SSL_KEY	如果设置，包含 SSL 私钥的文件名。
GRIST_TEST_LOGIN	允许伪造的未认证测试登录（仅适用于开发环境）。
GRIST_TEST_ROUTER	如果设置，则 home 服务将在 /test/router 提供 router api 的模拟版本
GREP_TESTS	用于选择要运行的特定测试的模式（例如 env GREP_TESTS=ActionLog yarn test）。

测试

当打开 PR 时，测试会作为 CI 的一部分自动运行。但是，在将更改推送到 GitHub 之前，在本地运行测试可能会有所帮助。首先，你需要确保已安装所有依赖项：

yarn install
yarn install:python

然后，你可以像这样运行主测试套件：

yarn test

Python 测试也可以在本地运行。（注意：目前需要 Python 3.10 - 3.11。）

yarn test:python

要运行特定测试，你可以使用 GREP_TESTS 变量指定模式：

env GREP_TESTS=ChoiceList yarn test
env GREP_TESTS=summary yarn test:python

许可证

本仓库 grist-core 在 Apache License, Version 2.0 下发布，这是经 OSI 批准的自由软件许可证。更多信息请参见 LICENSE.txt 和 NOTICE.txt。