跳转到内容
Zhang Accounting

S3

张记账可以直接在 Amazon S3 或兼容 S3 的存储（Cloudflare R2、MinIO、阿里云 OSS、腾讯云 COS、Backblaze B2 等）的存储桶中读写账本文件。这样服务器本身不保存任何数据，适合容器和托管平台。

配置

Section titled “配置”

用 --source s3 或 ZHANG_DATA_SOURCE=s3 选择这个数据源，并用环境变量配置它：

环境变量 必填 示例 说明
ZHANG_S3_BUCKET 是 my-ledger 存放账本的存储桶。
ZHANG_S3_ROOT 否 /accounting 账本在存储桶中所在的文件夹（键前缀）。默认为 /。
ZHANG_S3_ENDPOINT 否 https://<account_id>.r2.cloudflarestorage.com 存储服务的地址，除 Amazon S3 外都需要设置。未设置时依次读取 AWS_ENDPOINT_URL、AWS_ENDPOINT 或 AWS_S3_ENDPOINT，最后使用 https://s3.amazonaws.com。
ZHANG_S3_REGION 见说明 us-east-1 区域。未设置时依次读取 AWS_REGION 和 AWS_DEFAULT_REGION，三者必须设置其一。Cloudflare R2 使用 auto，MinIO 使用 us-east-1。
ZHANG_S3_ACCESS_KEY_ID 否 AKIA… 访问密钥 ID。未设置时使用标准的 AWS 凭证链：AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY、~/.aws 中的文件，最后是实例元数据。
ZHANG_S3_SECRET_ACCESS_KEY 否 访问密钥对应的秘密访问密钥。
ZHANG_S3_SESSION_TOKEN 否 临时凭证的会话令牌。
ZHANG_S3_VIRTUAL_HOST_STYLE 否 true 设为 true 或 1 时，以 https://<bucket>.<endpoint> 而不是 https://<endpoint>/<bucket> 的形式访问存储桶。有些服务商（例如阿里云 OSS）只接受这种形式。

zhang serve 的 <PATH> 参数会被忽略：账本就是存储桶中的 ZHANG_S3_ROOT 文件夹。主文件仍由 --endpoint 指定（默认为 main.zhang），相对于这个文件夹。

设置步骤

Section titled “设置步骤”
  1. 创建一个存储桶，并把账本文件上传进去，例如把 main.zhang 放在前缀 accounting/ 下。
  2. 创建能够读取、写入和列出该存储桶中对象的凭证（在 AWS 上为 GetObject、PutObject 和 ListBucket）。
  3. 设置好变量后启动张记账：
终端窗口
ZHANG_DATA_SOURCE=s3 \
ZHANG_S3_BUCKET=my-ledger \
ZHANG_S3_ROOT=/accounting \
ZHANG_S3_REGION=us-east-1 \
ZHANG_S3_ACCESS_KEY_ID=your_access_key \
ZHANG_S3_SECRET_ACCESS_KEY=your_secret \
zhang serve . --endpoint main.zhang

使用 Docker，账本位于 Cloudflare R2 存储桶的根目录时：

终端窗口
docker run --name zhang -d -p 8000:8000 \
  -e ZHANG_DATA_SOURCE=s3 \
  -e ZHANG_S3_BUCKET=my-ledger \
  -e ZHANG_S3_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com \
  -e ZHANG_S3_REGION=auto \
  -e ZHANG_S3_ACCESS_KEY_ID=your_access_key \
  -e ZHANG_S3_SECRET_ACCESS_KEY=your_secret \
  kilerd/zhang:latest

注意事项

Section titled “注意事项”
  • 公开 demo 可以使用只能读取和列举对象、不能写入或删除的凭据。设置步骤和编辑控件的限制见 Render demo 部署指南。
  • 张记账不会监视存储桶。文件在张记账之外发生变化时，请使用网页界面的重新加载按钮，或者重启张记账。你在网页界面中记录的内容会写入存储桶并立即重新加载。
  • 网页界面会把新条目、上传的文档和通行密钥写入存储桶，位置与本地文件系统相同。
  • 插件模块和网页界面打开过的文档会缓存在运行张记账的机器上、工作目录的 .cache 文件夹中，见 .cache 文件夹。

故障排除

Section titled “故障排除”
  • 张记账启动时报 cannot build s3 operator 和 region is missing 并退出：设置 ZHANG_S3_REGION（或 AWS_REGION）。对于不区分区域的服务，通常用 us-east-1 或 auto 即可。
  • 张记账启动时报 ZHANG_S3_BUCKET must be set 并退出：存储桶是必填项。
  • 访问被拒绝：为凭证授予该存储桶及对应前缀的读、写和列出权限。
  • 网页界面显示空账本：张记账没有找到主文件，于是以空账本启动。主文件从存储桶中的 <ZHANG_S3_ROOT>/<endpoint> 读取：请检查 ZHANG_S3_ROOT 和 --endpoint。