用 Grist 整理项目和收款台账

项目台账越写越长，同一个客户名称在好几个工作表里出现，改一次就要找好几个位置。Grist 可以用引用字段连接不同表，让客户、项目和付款各自保存，再按需要组合查看。

本文先做个人使用的台账，通过 SSH 隧道访问。公开给团队之前，需要单独完成身份认证与文档权限配置；GRIST_DEFAULT_EMAIL 指定初始管理员身份，不是一个登录密码。

准备个人台账的运行环境

Grist 会保存台账文档，选服务器时除了内存，也要考虑文档备份。需要新购 VPS，可以从雨云云服务器查看配置，再按要存的文档和使用人数确定资源。优惠码 KuZhuJi。如有消费返利，以购买页所选规格显示的金额为准。

以下命令在 Linux VPS 上执行，需要有 Docker 操作权限。先运行 docker version 和 docker compose version，确认引擎与 Compose v2 都能工作。没有安装 Docker 时，按 Docker 官方安装说明选择对应发行版；不要把其他发行版的仓库配置直接复制过来。

示例工作目录为 /opt/grist，所有相对路径都以这个目录为基准。VPS_IP、SSH 用户和示例域名需要换成自己的值。端口 8484 若已被占用，只改映射左侧的宿主机端口，并同步修改访问地址。

sudo install -d -m 0750 -o "$(id -u)" -g "$(id -g)" /opt/grist
cd /opt/grist
umask 077

保存 .env，将 openssl rand -hex 32 的输出填入会话密钥：

SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET
[email protected]

mkdir -p persist
chmod 600 .env

gvisor 用来隔离公式执行。若 VPS 缺少相应 CPU 或系统能力，按官方文档排查 XSAVE、ptrace 等条件；不要为了赶快打开界面就把沙箱关闭，再导入不明来源的文档。

将下面内容保存为 compose.yaml：

services:
  grist:
    image: gristlabs/grist:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8484:8484"
    environment:
      GRIST_SESSION_SECRET: ${SESSION_SECRET:?set random secret}
      GRIST_DEFAULT_EMAIL: ${ADMIN_EMAIL:?set your email}
      GRIST_SINGLE_ORG: personal
      GRIST_SANDBOX_FLAVOR: gvisor
    volumes:
      - ./persist:/persist

在工作目录启动并检查日志：

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

启动后按下面的步骤试用。遇到目录不可写的报错，先核对 UID 和挂载路径，不要直接改成 chmod 777。

用 SSH 隧道打开界面

示例仅把应用端口发布到 VPS 的 127.0.0.1。在自己的电脑上运行以下命令，保留终端窗口，再打开 http://127.0.0.1:8484：

ssh -N -L 8484:127.0.0.1:8484 your_ssh_user@VPS_IP

浏览器里的回环地址是自己的电脑，SSH 把请求转到 VPS。若本地同号端口被占用，可换隧道左侧端口；涉及应用外部 URL 的项目也要一起调整。管理界面无需因此开放公网端口。

把客户、项目和收款拆开

首次访问按引导完成安装设置。新建客户表，包含客户编号、名称和联系人；项目表只保存客户引用、项目名、状态与约定金额；付款表保存项目引用、日期与金额。

先用三条虚构项目和两笔虚构付款验证关系。一个项目有多笔付款时，按项目汇总付款，检查尚未付款、部分付款和已付清这三种情况。金额、日期应采用对应字段类型，别把“1,200 元”当作文本参与计算。

为自己建立“本月待收款”视图，并下载一份原生 Grist 文档，再重新导入为副本。CSV 可以给其他软件使用，但通常只保留表格数据，不能代替引用关系、布局和完整文档。

需要多人访问时，先依据官方说明配置身份认证，再设置 GRIST_FORCE_LOGIN=true 和文档权限。强制登录变量本身不提供认证服务。用第二个账号验证是否只能访问被授权文档，不能只看管理员界面。

备份台账和安装配置

persist 保存文档与安装数据，.env 保存身份和会话设置。恢复时检查原生文档、表间引用和计算结果。不要随意更换 GRIST_DEFAULT_EMAIL 或组织名称，它们会影响管理员和团队访问。

在工作目录执行下面的停机备份，压缩包保存在应用目录之外。停止全部服务会带来短暂不可用；确认停止成功后再打包。

docker compose stop
sudo install -d -m 0700 /var/backups/docker-apps
backup_file="/var/backups/docker-apps/$(basename "$PWD")-$(date +%Y%m%d-%H%M%S).tar.gz"
sudo tar -czpf "$backup_file" compose.yaml persist .env
sudo chmod 0600 "$backup_file"
sudo tar -tzf "$backup_file" | head
docker compose start

将压缩包复制到 VPS 之外。恢复时，在另一台测试机器的空目录解包，保留文件所有者和相对路径，用原镜像版本启动，检查前面提到的数据。不要直接覆盖正在使用的原数据目录。

升级前先记录镜像 ID 或摘要，并保存这份备份。阅读项目更新说明后再拉取镜像；涉及数据库迁移时，回滚需要恢复旧数据与旧镜像，不能只把标签改回去。

安装参数和数据路径可对照Grist 自托管文档。