Grist 本地测试指南使用 Docker Compose 一键启动 grist-core 实例【免费下载链接】grist-coreGrist is the evolution of spreadsheets.项目地址: https://gitcode.com/GitHub_Trending/gr/grist-coreGrist 是一款将电子表格的灵活性与数据库的健壮性相结合的现代关系型电子表格relational spreadsheet。本指南聚焦于仓库中官方提供的最简 Docker Compose 示例docker-compose-examples/grist-local-testing/讲解如何在本地以最小步骤启动一个可用的 Grist 实例从运行docker compose up到访问http://localhost:8484并深入剖析示例背后的镜像默认配置、持久化目录结构与容器入口脚本的权限处理逻辑帮助你在 5 分钟内完成本地环境搭建并为后续对接认证、HTTPS 等生产级部署打下基础。一、示例定位专为本地测试设计的最简部署在进入操作之前先明确这个示例的定位。仓库中的docker-compose-examples/目录按部署复杂度提供了多套编排方案而本指南讨论的 grist-local-testing 是其中最简单的一版官方对其定位的原文是This is the simplest example that runs Grist, suitable for local testing.也就是说它的目标场景是本地开发、功能试用、快速验证而不是面向公网的生产部署。整个示例只包含一个 Grist 服务没有任何认证网关、数据库或对象存储组件因此官方在 README 中给出了非常明确的安全警告It is STRONGLY RECOMMENDED not to use this container in a way that makes it accessible to the internet. This setup lacks basic security or authentication.强烈不建议以任何方式让该容器对互联网开放访问。此配置缺少基本的安全或认证机制。换句话说这套配置开箱即用、零配置但没有认证——任何能访问到该端口的人都可以直接操作文档。其余示例如grist-traefik-basic-auth、grist-traefik-oidc-auth则演示了如何补齐认证与 HTTPS本指南的最后一节会给出对比与进阶方向。二、快速启动从命令到界面运行该示例的操作步骤非常简单。首先进入示例所在目录然后执行docker compose up命令执行成功后Grist 容器会监听宿主机的8484端口此时在浏览器中访问http://localhost:8484即可看到 Grist 的主界面直接开始创建和组织电子表格文档。这里的几个关键点值得展开说明端口8484的由来它并非 Compose 文件凭空指定而是与 Dockerfile 中的EXPOSE 8484声明保持一致同时 docker-compose.yml 通过ports: - 8484:8484将容器端口映射到宿主机。默认的docker run等价方式在 Dockerfile 注释 中也有体现docker run -p 8484:8484 -it image。数据落盘该实例会把文档与相关文件保存在示例目录下的persist/子目录中详见第三节。首启镜像拉取首次执行时 Docker 会自动拉取gristlabs/grist:latest镜像需要保证网络可达 Docker Hub。三、逐行解读 docker-compose.yml整个示例的编排文件极其精简只有短短 8 行完整内容如下services: grist: image: gristlabs/grist:latest volumes: # Where to store persistent data, such as documents. - ${PERSIST_DIR:-./persist}/grist:/persist ports: - 8484:8484逐项拆解如下配置项值说明imagegristlabs/grist:latest使用官方发布的最新版 Grist 镜像volumes${PERSIST_DIR:-./persist}/grist:/persist将宿主机目录挂载到容器内的/persist用于持久化文档数据ports8484:8484将容器内 8484 端口映射到宿主机 8484 端口其中有两个设计细节值得注意挂载路径使用了变量插值${PERSIST_DIR:-./persist}表示「若设置了PERSIST_DIR环境变量则使用其值否则回退到相对路径./persist」。因此默认情况下文档数据落在执行docker compose up的目录下的persist/grist/子目录中。宿主机路径到容器路径的映射容器内部约定/persist为数据根目录见 Dockerfile 中的RUN mkdir -p /persist/docs而挂载点.../grist:/persist意味着你可以在宿主机persist/grist/目录下直接看到并备份 Grist 的持久化文件。自定义数据存放位置PERSIST_DIR如果你希望把数据放到其他位置例如独立的数据盘或统一的数据目录不需要修改 Compose 文件只需在启动时注入环境变量即可。以下两种写法等价# 方式一在 shell 中导出变量后执行 export PERSIST_DIR/data/grist docker compose up # 方式二内联注入 PERSIST_DIR/data/grist docker compose up该变量的用法同样贯穿于其他示例在 grist-traefik-basic-auth/docker-compose.yml 与 grist-with-postgres-redis-minio/docker-compose.yml 中它被用于统一指定所有组件Grist、PostgreSQL、Redis、MinIO的持久化根目录。需要注意的是这些示例使用的是${PERSIST_DIR}不带默认值即必须显式设置该变量才能启动而本地测试示例带有:-./persist回退可以直接零配置运行。四、容器内部/persist 目录与默认环境变量挂载到容器内的/persist目录是理解这套方案的关键。从 Dockerfile 的运行时阶段node:22-trixie-slim基础镜像之上可以看到 Grist 官方镜像为「开箱即用」预设了一整套默认环境变量ENV \ GRIST_ORG_IN_PATHtrue \ GRIST_HOST0.0.0.0 \ GRIST_SINGLE_PORTtrue \ GRIST_SERVE_SAME_ORIGINtrue \ GRIST_DATA_DIR/persist/docs \ GRIST_INST_DIR/persist \ GRIST_SESSION_COOKIEgrist_core \ GVISOR_FLAGS-unprivileged -ignore-cgroups \ NODE_OPTIONS--no-deprecation \ NODE_ENVproduction \ TYPEORM_DATABASE/persist/home.sqlite3这些变量共同决定了本地测试实例的行为GRIST_DATA_DIR/persist/docs文档数据目录对应宿主机挂载卷下的grist/docs/Grist 的.grist文档文件保存在这里。GRIST_INST_DIR/persist安装目录Grist 元数据如插件、扩展等的存放根。TYPEORM_DATABASE/persist/home.sqlite3家庭数据库使用 SQLite数据库文件即/persist/home.sqlite3用于存储用户、组织、工作区等站点级信息。GRIST_HOST0.0.0.0GRIST_SINGLE_PORTtrueGRIST_SERVE_SAME_ORIGINtrue让服务监听所有网络接口并以单端口、同源方式对外提供服务——这正是浏览器只需访问一个8484端口即可完成全部交互的原因。NODE_ENVproduction如 Dockerfile 注释 所述该设置会给予 ActiveDoc 操作更充裕的执行时间并让 Express Web 服务器进行一些精简优化。因此宿主机上persist/grist/目录的典型结构为persist/grist/ ├── docs/ # Grist 文档.grist 文件对应 GRIST_DATA_DIR └── home.sqlite3 # 站点级 SQLite 数据库对应 TYPEORM_DATABASE备份时直接备份整个挂载目录即可由于 Grist 文档基于 SQLite任何能读取 SQLite 的工具都能读取文档中的数值与文本数据这大大方便了备份与迁移项目 README 中将其称为 A portable, self-contained format。五、启动链路入口脚本与权限降级了解容器启动时发生了什么有助于排查权限类问题。镜像的启动链路由两部分脚本构成ENTRYPOINT [./sandbox/docker_entrypoint.sh]负责权限准备。脚本docker_entrypoint.sh的核心逻辑是若当前以 root 启动id -u为 0则将/persist下所有文件的所有权调整给非特权用户grist对应GRIST_DOCKER_USERgrist、GRIST_DOCKER_GROUPgrist两个环境变量随后通过setpriv降级并以该用户身份重新执行自身最后用tini作为 init 进程拉起真正的命令。这样可以避免 Grist 以 root 身份长时间运行降低安全风险。CMD [./sandbox/run.sh]真正的服务启动。脚本run.sh会先根据GRIST_SANDBOX_FLAVOR环境变量决定沙箱类型——若为gvisor则先校验 gVisor 运行参数GVISOR_FLAGS并更新引擎检查点最后执行node _build/stubs/app/server/server.js启动 Grist 服务端。理解这一点对本地测试的实际意义在于如果你挂载了一个由 root 创建、权限受限的目录容器会自动尝试修正所有权而当目录权限异常时入口脚本也会明确报错退出Invalid permissions, cannot write ... Aborting.方便快速定位问题。六、安全边界与生产级部署进阶这套最简示例的价值在于「快速可用」但它刻意不包含任何安全组件。从仓库中其他示例可以看到要安全地对外提供服务通常需要补齐以下能力能力对应示例关键配置基本认证Basic Authgrist-traefik-basic-authGRIST_FORWARD_AUTH_HEADER: X-Forwarded-User、GRIST_FORCE_LOGIN: true、GRIST_DEFAULT_EMAIL、APP_HOME_URL配合 Traefik 反向代理做 TLS 与认证单点登录OIDCgrist-traefik-oidc-auth通过 OIDC Provider 实现身份认证生产级数据层grist-with-postgres-redis-minio以 PostgreSQL 替代 SQLiteTYPEORM_TYPE: postgres及TYPEORM_HOST等变量、引入 RedisREDIS_URL与 MinIOGRIST_DOCS_MINIO_*系列变量作为文档存储对比可见本地测试示例中的GRIST_SINGLE_ORG、GRIST_FORCE_LOGIN等认证相关变量均未设置因此服务完全匿名、无登录环节。正确的用法是仅在本机或可信内网环境进行试用如需公网访问请参照其他示例或官方支持文档先行配置认证与 HTTPS。七、常见问题速查访问http://localhost:8484无响应确认docker compose up输出中 Grist 已成功启动且宿主机防火墙未拦截 8484 端口。想更换数据目录设置PERSIST_DIR环境变量例如PERSIST_DIR/data/grist docker compose up数据将落在/data/grist/grist/下。想重置实例停止容器后删除persist/目录或仅删除其中的docs/与home.sqlite3再重新docker compose up即可获得一个全新实例。注意直接删除目录前请确认其中没有需要保留的文档。容器以 root 启动时的权限处理无需手动干预入口脚本会自动将/persist所有权移交给非特权grist用户并降权运行。该实例能否用于生产不能。它缺少认证与 HTTPS仅适合本地测试生产环境请参考仓库中带认证、数据库与对象存储的示例。八、小结grist-local-testing示例以一份 8 行的 Compose 文件浓缩了 Grist 单机部署的全部核心要素官方镜像、8484端口、/persist持久化目录与可自定义的PERSIST_DIR变量。配合 Dockerfile 中的默认环境变量与 docker_entrypoint.sh 的权限降级机制它既能让你在一分钟内跑起一个功能完整的 Grist 实例也为你理解 Grist 容器化部署的数据布局与启动链路提供了最直观的入口。从这版最简示例出发你可以在同一仓库的docker-compose-examples/目录下继续探索 Traefik 认证、PostgreSQL/Redis/MinIO 等进阶编排方案平滑过渡到生产部署。【免费下载链接】grist-coreGrist is the evolution of spreadsheets.项目地址: https://gitcode.com/GitHub_Trending/gr/grist-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Grist 本地测试指南：使用 Docker Compose 一键启动 grist-core 实例
Grist 本地测试指南使用 Docker Compose 一键启动 grist-core 实例【免费下载链接】grist-coreGrist is the evolution of spreadsheets.项目地址: https://gitcode.com/GitHub_Trending/gr/grist-coreGrist 是一款将电子表格的灵活性与数据库的健壮性相结合的现代关系型电子表格relational spreadsheet。本指南聚焦于仓库中官方提供的最简 Docker Compose 示例docker-compose-examples/grist-local-testing/讲解如何在本地以最小步骤启动一个可用的 Grist 实例从运行docker compose up到访问http://localhost:8484并深入剖析示例背后的镜像默认配置、持久化目录结构与容器入口脚本的权限处理逻辑帮助你在 5 分钟内完成本地环境搭建并为后续对接认证、HTTPS 等生产级部署打下基础。一、示例定位专为本地测试设计的最简部署在进入操作之前先明确这个示例的定位。仓库中的docker-compose-examples/目录按部署复杂度提供了多套编排方案而本指南讨论的 grist-local-testing 是其中最简单的一版官方对其定位的原文是This is the simplest example that runs Grist, suitable for local testing.也就是说它的目标场景是本地开发、功能试用、快速验证而不是面向公网的生产部署。整个示例只包含一个 Grist 服务没有任何认证网关、数据库或对象存储组件因此官方在 README 中给出了非常明确的安全警告It is STRONGLY RECOMMENDED not to use this container in a way that makes it accessible to the internet. This setup lacks basic security or authentication.强烈不建议以任何方式让该容器对互联网开放访问。此配置缺少基本的安全或认证机制。换句话说这套配置开箱即用、零配置但没有认证——任何能访问到该端口的人都可以直接操作文档。其余示例如grist-traefik-basic-auth、grist-traefik-oidc-auth则演示了如何补齐认证与 HTTPS本指南的最后一节会给出对比与进阶方向。二、快速启动从命令到界面运行该示例的操作步骤非常简单。首先进入示例所在目录然后执行docker compose up命令执行成功后Grist 容器会监听宿主机的8484端口此时在浏览器中访问http://localhost:8484即可看到 Grist 的主界面直接开始创建和组织电子表格文档。这里的几个关键点值得展开说明端口8484的由来它并非 Compose 文件凭空指定而是与 Dockerfile 中的EXPOSE 8484声明保持一致同时 docker-compose.yml 通过ports: - 8484:8484将容器端口映射到宿主机。默认的docker run等价方式在 Dockerfile 注释 中也有体现docker run -p 8484:8484 -it image。数据落盘该实例会把文档与相关文件保存在示例目录下的persist/子目录中详见第三节。首启镜像拉取首次执行时 Docker 会自动拉取gristlabs/grist:latest镜像需要保证网络可达 Docker Hub。三、逐行解读 docker-compose.yml整个示例的编排文件极其精简只有短短 8 行完整内容如下services: grist: image: gristlabs/grist:latest volumes: # Where to store persistent data, such as documents. - ${PERSIST_DIR:-./persist}/grist:/persist ports: - 8484:8484逐项拆解如下配置项值说明imagegristlabs/grist:latest使用官方发布的最新版 Grist 镜像volumes${PERSIST_DIR:-./persist}/grist:/persist将宿主机目录挂载到容器内的/persist用于持久化文档数据ports8484:8484将容器内 8484 端口映射到宿主机 8484 端口其中有两个设计细节值得注意挂载路径使用了变量插值${PERSIST_DIR:-./persist}表示「若设置了PERSIST_DIR环境变量则使用其值否则回退到相对路径./persist」。因此默认情况下文档数据落在执行docker compose up的目录下的persist/grist/子目录中。宿主机路径到容器路径的映射容器内部约定/persist为数据根目录见 Dockerfile 中的RUN mkdir -p /persist/docs而挂载点.../grist:/persist意味着你可以在宿主机persist/grist/目录下直接看到并备份 Grist 的持久化文件。自定义数据存放位置PERSIST_DIR如果你希望把数据放到其他位置例如独立的数据盘或统一的数据目录不需要修改 Compose 文件只需在启动时注入环境变量即可。以下两种写法等价# 方式一在 shell 中导出变量后执行 export PERSIST_DIR/data/grist docker compose up # 方式二内联注入 PERSIST_DIR/data/grist docker compose up该变量的用法同样贯穿于其他示例在 grist-traefik-basic-auth/docker-compose.yml 与 grist-with-postgres-redis-minio/docker-compose.yml 中它被用于统一指定所有组件Grist、PostgreSQL、Redis、MinIO的持久化根目录。需要注意的是这些示例使用的是${PERSIST_DIR}不带默认值即必须显式设置该变量才能启动而本地测试示例带有:-./persist回退可以直接零配置运行。四、容器内部/persist 目录与默认环境变量挂载到容器内的/persist目录是理解这套方案的关键。从 Dockerfile 的运行时阶段node:22-trixie-slim基础镜像之上可以看到 Grist 官方镜像为「开箱即用」预设了一整套默认环境变量ENV \ GRIST_ORG_IN_PATHtrue \ GRIST_HOST0.0.0.0 \ GRIST_SINGLE_PORTtrue \ GRIST_SERVE_SAME_ORIGINtrue \ GRIST_DATA_DIR/persist/docs \ GRIST_INST_DIR/persist \ GRIST_SESSION_COOKIEgrist_core \ GVISOR_FLAGS-unprivileged -ignore-cgroups \ NODE_OPTIONS--no-deprecation \ NODE_ENVproduction \ TYPEORM_DATABASE/persist/home.sqlite3这些变量共同决定了本地测试实例的行为GRIST_DATA_DIR/persist/docs文档数据目录对应宿主机挂载卷下的grist/docs/Grist 的.grist文档文件保存在这里。GRIST_INST_DIR/persist安装目录Grist 元数据如插件、扩展等的存放根。TYPEORM_DATABASE/persist/home.sqlite3家庭数据库使用 SQLite数据库文件即/persist/home.sqlite3用于存储用户、组织、工作区等站点级信息。GRIST_HOST0.0.0.0GRIST_SINGLE_PORTtrueGRIST_SERVE_SAME_ORIGINtrue让服务监听所有网络接口并以单端口、同源方式对外提供服务——这正是浏览器只需访问一个8484端口即可完成全部交互的原因。NODE_ENVproduction如 Dockerfile 注释 所述该设置会给予 ActiveDoc 操作更充裕的执行时间并让 Express Web 服务器进行一些精简优化。因此宿主机上persist/grist/目录的典型结构为persist/grist/ ├── docs/ # Grist 文档.grist 文件对应 GRIST_DATA_DIR └── home.sqlite3 # 站点级 SQLite 数据库对应 TYPEORM_DATABASE备份时直接备份整个挂载目录即可由于 Grist 文档基于 SQLite任何能读取 SQLite 的工具都能读取文档中的数值与文本数据这大大方便了备份与迁移项目 README 中将其称为 A portable, self-contained format。五、启动链路入口脚本与权限降级了解容器启动时发生了什么有助于排查权限类问题。镜像的启动链路由两部分脚本构成ENTRYPOINT [./sandbox/docker_entrypoint.sh]负责权限准备。脚本docker_entrypoint.sh的核心逻辑是若当前以 root 启动id -u为 0则将/persist下所有文件的所有权调整给非特权用户grist对应GRIST_DOCKER_USERgrist、GRIST_DOCKER_GROUPgrist两个环境变量随后通过setpriv降级并以该用户身份重新执行自身最后用tini作为 init 进程拉起真正的命令。这样可以避免 Grist 以 root 身份长时间运行降低安全风险。CMD [./sandbox/run.sh]真正的服务启动。脚本run.sh会先根据GRIST_SANDBOX_FLAVOR环境变量决定沙箱类型——若为gvisor则先校验 gVisor 运行参数GVISOR_FLAGS并更新引擎检查点最后执行node _build/stubs/app/server/server.js启动 Grist 服务端。理解这一点对本地测试的实际意义在于如果你挂载了一个由 root 创建、权限受限的目录容器会自动尝试修正所有权而当目录权限异常时入口脚本也会明确报错退出Invalid permissions, cannot write ... Aborting.方便快速定位问题。六、安全边界与生产级部署进阶这套最简示例的价值在于「快速可用」但它刻意不包含任何安全组件。从仓库中其他示例可以看到要安全地对外提供服务通常需要补齐以下能力能力对应示例关键配置基本认证Basic Authgrist-traefik-basic-authGRIST_FORWARD_AUTH_HEADER: X-Forwarded-User、GRIST_FORCE_LOGIN: true、GRIST_DEFAULT_EMAIL、APP_HOME_URL配合 Traefik 反向代理做 TLS 与认证单点登录OIDCgrist-traefik-oidc-auth通过 OIDC Provider 实现身份认证生产级数据层grist-with-postgres-redis-minio以 PostgreSQL 替代 SQLiteTYPEORM_TYPE: postgres及TYPEORM_HOST等变量、引入 RedisREDIS_URL与 MinIOGRIST_DOCS_MINIO_*系列变量作为文档存储对比可见本地测试示例中的GRIST_SINGLE_ORG、GRIST_FORCE_LOGIN等认证相关变量均未设置因此服务完全匿名、无登录环节。正确的用法是仅在本机或可信内网环境进行试用如需公网访问请参照其他示例或官方支持文档先行配置认证与 HTTPS。七、常见问题速查访问http://localhost:8484无响应确认docker compose up输出中 Grist 已成功启动且宿主机防火墙未拦截 8484 端口。想更换数据目录设置PERSIST_DIR环境变量例如PERSIST_DIR/data/grist docker compose up数据将落在/data/grist/grist/下。想重置实例停止容器后删除persist/目录或仅删除其中的docs/与home.sqlite3再重新docker compose up即可获得一个全新实例。注意直接删除目录前请确认其中没有需要保留的文档。容器以 root 启动时的权限处理无需手动干预入口脚本会自动将/persist所有权移交给非特权grist用户并降权运行。该实例能否用于生产不能。它缺少认证与 HTTPS仅适合本地测试生产环境请参考仓库中带认证、数据库与对象存储的示例。八、小结grist-local-testing示例以一份 8 行的 Compose 文件浓缩了 Grist 单机部署的全部核心要素官方镜像、8484端口、/persist持久化目录与可自定义的PERSIST_DIR变量。配合 Dockerfile 中的默认环境变量与 docker_entrypoint.sh 的权限降级机制它既能让你在一分钟内跑起一个功能完整的 Grist 实例也为你理解 Grist 容器化部署的数据布局与启动链路提供了最直观的入口。从这版最简示例出发你可以在同一仓库的docker-compose-examples/目录下继续探索 Traefik 认证、PostgreSQL/Redis/MinIO 等进阶编排方案平滑过渡到生产部署。【免费下载链接】grist-coreGrist is the evolution of spreadsheets.项目地址: https://gitcode.com/GitHub_Trending/gr/grist-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考