Grist 保姆级部署教程：现代关系型电子表格，把数据库能力装进表格里

一、项目介绍

Grist 是一款"现代关系型电子表格"（官方 README 原文："Grist is a modern relational spreadsheet. It combines the flexibility of a spreadsheet with the robustness of a database."）。它由美国纽约的 Grist Labs 公司开发，法国政府组织 ANCT Données et Territoires 与 DINUM 也对代码库有重要贡献。与传统电子表格不同，Grist 的列在概念上更接近数据库字段——列有名称、只存放一种数据类型，并且可以用公式（支持完整 Python 语法）自动计算，当被引用的单元格变化时结果自动更新。

官方仓库 grist-core（又称 Grist Community edition）提供运行服务端所需的全部代码；另外还有 grist-desktop（Linux/macOS/Windows 桌面应用）与 grist-static（纯浏览器构建，无需后端即可在网页上展示表格）三个开源仓库，均采用 Apache License 2.0。项目在 GitHub（gristlabs/grist-core）持续活跃维护，官方提供 Docker 镜像 gristlabs/grist 与 gristlabs/grist-oss，以及托管服务 getgrist.com。

二、功能拆解

按官方 README「Features in grist-core」一节，核心功能如下：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/gristlabs/grist-core
• 官方网站：https://www.getgrist.com
• 官方文档：https://support.getgrist.com
• 自托管文档：https://support.getgrist.com/self-managed/
• 首次运行向导：https://support.getgrist.com/install/first-run-setup/
• 模板库：https://templates.getgrist.com
• Docker 镜像：https://hub.docker.com/r/gristlabs/grist
• 社区论坛：https://community.getgrist.com/ ｜ Discord：https://discord.gg/MYKpYQ3fbP

四、环境要求

官方 README「Using Grist」一节明确：在本机运行默认版本的 grist-core 需要安装 Docker。

• 端口：官方默认监听 8484（PORT 环境变量控制）。
• 数据目录：容器内 /persist，官方默认文档目录为 /persist/docs（环境变量 GRIST_DATA_DIR 默认值）。
• 操作系统：官方 Docker 镜像可在任何支持 Docker 的系统上运行；源码构建支持 Linux/macOS/Windows（沙箱方式不同）。
• 硬件：官方 README 未给出最低硬件指标。
• 依赖：仅 Docker；官方另提供从源码构建方式（需 yarn、Python 3.10–3.11）。

五、部署步骤

步骤 1：拉取官方镜像

docker pull gristlabs/grist

逐段解释：docker pull 从 Docker Hub 拉取镜像；gristlabs/grist 是官方默认镜像，包含 Grist Community edition 全部功能以及 Full edition 的扩展（扩展仅在 Admin Panel 切到 "Full Grist" 时激活，Community 模式下不生效）。若只想要纯开源代码，官方提供 gristlabs/grist-oss 镜像。

预期输出参考： Docker 拉取进度条，结束显示状态 Downloaded newer image for gristlabs/grist:latest 之类。

步骤 2：启动容器（官方最小命令）

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

逐段解释：docker run 运行容器；-p 8484:8484 将本机 8484 端口映射到容器 8484；-it 附加终端便于观察启动日志；gristlabs/grist 为镜像名。官方 README 原文："Then visit http://localhost:8484 in your browser."

预期输出参考： 容器启动日志中出现一行 BOOT KEY: <random-string>（新安装自动生成的引导密钥），随后服务监听 8484 端口。

步骤 3：浏览器访问并完成首次设置

官方 README 原文："On a brand new install you'll land on a Quick setup page that walks you through choosing an admin email, picking how people sign in, and setting who can use the site. To get past the first screen, look in the container's startup log for a line containing a generated boot key, and paste it in when prompted. Once you click Apply and go live! at the end of Quick setup, the site is open for business."

即：浏览器打开 http://服务器IP:8484，在 Quick setup 页面粘贴启动日志中的 boot key，填写管理员邮箱、选择登录方式与开放范围，最后点击 Apply and go live!。

步骤 4（推荐）：持久化数据目录

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

逐段解释：官方 README 原文："To preserve your work across docker runs, share a directory as /persist." -v $PWD/persist:/persist 将宿主当前目录下的 persist/ 挂载为容器内 /persist，文档与附件保存在其中，容器删除后数据不丢。

步骤 5（可选）：自定义端口

官方 README 原文："If you need to change the port Grist runs on, set a PORT variable, don't just change the port mapping:"

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

逐段解释：--env PORT=9999 设置 Grist 服务监听端口为 9999；-p 9999:9999 宿主与容器端口一致映射。官方强调不要只改 -p 映射而不改容器内 PORT。

步骤 6（可选）：指定自己的 boot key

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

逐段解释：官方 README 原文："If you'd rather pick your own boot key, set GRIST_BOOT_KEY." 默认新安装自动生成 boot key 并打印到容器日志；设置 GRIST_BOOT_KEY 后即用自己指定的值。

步骤 7（可选）：跳过 Quick setup，直接开放单用户

docker run --env GRIST_IN_SERVICE=true -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist

逐段解释：官方 README 原文："If you'd rather skip Quick setup entirely and start with an open, single-user setup, set GRIST_IN_SERVICE=true." 该变量使服务器跳过首次设置门槛直接进入服务状态。

六、配置参数详解

Grist 通过环境变量配置，官方 README「Environment variables」一节列出全部敏感变量。常用项如下：

数据库相关（TypeORM）： 默认使用 SQLite；如需 PostgreSQL，官方环境变量表给出 TYPEORM_TYPE=postgres、TYPEORM_HOST、TYPEORM_PORT、TYPEORM_DATABASE、TYPEORM_USERNAME、TYPEORM_PASSWORD、TYPEORM_EXTRA（JSON）。

七、启动与运维

• 前台启动： docker run -p 8484:8484 -it gristlabs/grist（官方原命令，终端占用）。
• 后台运行： 官方 README 未给出专用后台命令；可使用 Docker 平台通用的 -d 参数替代 -it（如 docker run -d -p 8484:8484 ...），此属 Docker 原生能力而非 Grist 官方文档内容。
• 停止： 在前台终端按 Ctrl+C；后台容器用 docker stop <容器名>。
• 查看日志： 前台直接看终端输出；后台用 docker logs <容器名>（boot key 在启动日志中）。
• 开机自启： 官方 README 未提供 Grist 专用自启配置；如需容器随 Docker 守护进程自动拉起，可使用 Docker 通用的 --restart=unless-stopped 或 --restart=always 参数（Docker 原生能力）。
• 数据持久化： 官方方式为 -v $PWD/persist:/persist 挂载宿主目录；文档默认存于 /persist/docs。
• Admin Panel： 访问 http://服务器IP:8484/admin，用 boot key 登录，可查看健康探针、修改设置、切换 edition。官方 README："Visit /admin on your Grist server to find it."
• gVisor 沙箱： 官方命令 --env GRIST_SANDBOX_FLAVOR=gvisor 启用（"This should work with default docker settings, but may not work in all environments."）。

八、实操验证

1. 浏览器访问 http://服务器IP:8484，应看到 Quick setup 页面（新安装）。
2. 在容器启动日志中找到 BOOT KEY: <random-string>，粘贴到页面输入框。
3. 填写管理员邮箱、选择登录方式（默认匿名/Google/Authentik 等）、设置谁可以使用站点，点击 Apply and go live!。
4. 进入主界面后，点击新建文档（Create New Document），默认会得到一个空表格。
5. 在第一列输入几行数据，新增一列时选择「Formula」类型，输入公式如 $A * 2（$A 引用 A 列），确认公式自动计算且修改 A 列时结果联动——即验证 Grist 的"数据库式电子表格"核心能力。
6. 访问 http://服务器IP:8484/admin，用同一 boot key 登录，应看到 Admin Panel 的健康探针列表。

登录与安全（重要）

• 官方默认账号密码：无默认账号密码。 Grist 出厂没有内置用户。首次访问走 Quick setup 向导，由操作者自己填写管理员邮箱并选择登录方式。
• Boot Key（管理员引导密钥）： 新安装自动生成并打印在容器启动日志中（BOOT KEY: <random-string>），用于首次进入 Quick setup 与 Admin Panel；可通过环境变量 GRIST_BOOT_KEY=secret 自定义。官方 README 明确："New installs generate a boot key automatically and print it to the container log on startup."
• 登录方式： Quick setup 中可选。最简方式是 GRIST_DEFAULT_EMAIL=my@email（官方原命令），此后"Sign in"按钮将工作归属到该邮箱，无需密码；多用户/公网部署应接 SSO（Sign in with getgrist.com、forwarded headers、OIDC、SAML，后两者需 Full edition 激活密钥）。
• 修改密码/身份： 单用户模式下在 User Menu → Profile Settings 中修改显示名称；密码体系由所选 SSO 提供方决定，Grist 不存储用户密码。
• 密码/密钥存放位置： GRIST_SESSION_SECRET 编码会话；文档数据存于 /persist/docs（SQLite）；boot key 仅在启动日志或 GRIST_BOOT_KEY 环境变量中。
• 安全提醒：部署到公网前必须完成 Quick setup 并配置认证方式；官方 README 警告 REQUEST 函数、webhook 等功能存在 SSRF 风险，公网部署应配合 ALLOWED_WEBHOOK_DOMAINS 与 GRIST_PROXY_FOR_UNTRUSTED_URLS 收敛。

九、故障排查

案例 1：Quick setup 页面提示 boot key 无效或找不到

• 报错原文：进入 http://服务器IP:8484 的 Quick setup 或 /admin 页面要求输入 boot key，但日志中找不到对应行。
• 报错原因：官方 README 说明 boot key 打印在容器启动日志中；若容器以 -d 后台运行后日志被滚走，或未设置 GRIST_BOOT_KEY 而日志未被及时查看，都会导致丢失。
• 分步解决：① 重新查看容器日志 docker logs <容器名> 2>&1 | grep "BOOT KEY"；② 如确实找不到，按官方建议用环境变量自定义：docker run -e GRIST_BOOT_KEY=myownkey ... 重新创建容器（配合 -v $PWD/persist:/persist 保留数据）；③ 用自定义 key 登录 Quick setup / Admin Panel。

案例 2：只改了 -p 端口映射，容器内仍监听 8484 导致访问异常

• 报错原文：页面打不开或访问到错误服务。
• 报错原因：官方 README 原文警告："If you need to change the port Grist runs on, set a PORT variable, don't just change the port mapping."
• 分步解决：① 停止当前容器；② 按官方命令同时设置 --env PORT=9999 -p 9999:9999 重新运行；③ 浏览器访问 http://服务器IP:9999。

案例 3：gVisor 沙箱在当前环境不可用

• 报错原文（常见形式）：容器启动后文档运行公式时报沙箱相关错误，或 gVisor runsc 未安装。
• 报错原因：官方 README 原文："This should work with default docker settings, but may not work in all environments." gVisor 需宿主机安装 runsc。
• 分步解决：① 不设置 GRIST_SANDBOX_FLAVOR=gvisor，改用官方列出的其他沙箱方式：macOS 用 macSandboxExec，任意 OS（含 Windows）用 pyodide（Deno+Pyodide Wasm 沙箱）；② 对应命令示例：docker run --env GRIST_SANDBOX_FLAVOR=pyodide -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist。

案例 4：容器删除后数据丢失

• 报错原文：重新 docker run 后文档全部消失。
• 报错原因：未挂载 /persist 卷，数据存于容器可写层。
• 分步解决：按官方命令加 -v $PWD/persist:/persist 重新运行；如之前未备份，数据随容器删除而永久丢失，后续务必持久化。

十、升级、回滚与卸载

升级： 官方 README 未提供专门的升级命令；基于 Docker 镜像机制，升级流程为：① docker pull gristlabs/grist 拉取最新镜像；② 用相同 -v $PWD/persist:/persist 参数重新 docker run 创建容器（数据在 /persist 卷中保留）。如需固定版本，可将镜像名替换为带标签的 gristlabs/grist:<版本号>（标签列表见 Docker Hub）。

回滚： 官方未提供一键回滚命令；基于 Docker 镜像标签机制，将镜像指定为旧版本标签后按升级同款命令重新运行容器（/persist 卷保留）。

卸载： ① docker stop <容器名> && docker rm <容器名> 删除容器；② 如需彻底删除数据，删除宿主持久化目录 persist/（此操作永久删除全部文档，务必先备份——可 cp -r persist /备份目录）；③ docker rmi gristlabs/grist 删除镜像。

十一、商用许可合规说明

• 许可证：Apache License, Version 2.0（官方 README「License」一节明确："This repository, grist-core, is released under the Apache License, Version 2.0, which is an OSI-approved free software license. See LICENSE.txt and NOTICE.txt for more information."）。
• Apache-2.0 允许自由使用、修改、分发与商用（包括闭源商业产品），但分发时须保留版权声明与许可文本，修改过的文件须标注变更，并附带 NOTICE（如有）。
• 注意：官方默认镜像 gristlabs/grist 中还打包了 Full edition 的扩展代码，"These extensions are not under a free or open-source license"——这些扩展仅在 Admin Panel 切换到 "Full Grist" 时激活，Community 模式下不生效。若要求纯开源镜像，官方提供 gristlabs/grist-oss（"functionally equivalent to the gristlabs/grist image whose edition is set to Community Grist"）。
• Grist Labs 是 open-core 公司，grist-core 商用部署无需付费授权；Full edition 企业功能需激活密钥（见官方 FAQ）。