以下端点通过 X-Api-Token 标头受 API 密钥保护，并且除非将 --api-key 选项传递给二进制文件或设置 PICTRS__SERVER__API_KEY 环境变量，否则它们将禁用。

可以通过任何密码生成器生成安全的 API 密钥。

• POST /internal/import 用于上传图像，同时保留文件名作为第一个别名。上传格式和响应格式与 POST /image 端点相同。

• POST /internal/delete?alias={alias} 无需删除令牌即可删除别名。可用的源参数有

  • ?alias={alias} 删除文件别名
  • ?proxy={url} 删除代理文件的别名

  此端点返回以下 JSON

  {
      "msg": "ok",
  }
  

• POST /internal/purge?alias={alias} 通过别名清除文件。这将删除与查询相关联的所有别名和文件。

  可用源参数包括

  • ?alias={alias} 通过别名清除文件
  • ?proxy={url} 通过 URL 清除代理文件

  此端点返回以下 JSON

  {
      "msg": "ok",
      "aliases": ["asdf.png"]
  }
  

• GET /internal/aliases?alias={alias} 通过别名获取文件的别名

  可用源参数包括

  • ?alias={alias} 通过提供的别名获取文件的全部别名
  • ?proxy={url} 通过URL获取代理文件的全部别名

  此端点返回与清除端点相同的JSON

• DELETE /internal/variants 为上传图像生成的变体排队清理。

  如果再次获取清理的变体，它们将重新生成。

• GET /internal/identifier?alias={alias} 获取给定别名的图像标识符（文件路径或对象路径）。

  可用源参数包括

  • ?alias={alias} 通过提供的别名获取文件的标识符
  • ?proxy={url} 通过URL获取代理文件的标识符

  成功时，返回的JSON应如下所示

  {
      "msg": "ok",
      "identifier": "/path/to/object"
  }
  

• POST /internal/set_not_found?alias={alias} 设置从原始和处理端点服务404图像。使用的图像必须已经上传并具有别名。请求应如下所示

  {
      "alias": "asdf.png"
  }
  

  成功时，返回的JSON应如下所示

  {
      "msg": "ok"
  }
  

  如果pict-rs找不到提供的别名，它将返回以下JSON的400 Bad Request

  {
      "msg": "No hash associated with provided alias"
  }
  

• POST /internal/export 将当前sled数据库导出到配置的export_path。这对于备份正在运行的pict-rs服务器非常有用。成功时，它将返回

  {
      "msg": "ok"
  }
  

  从导出的数据库恢复就像这样

  1. 停止pict-rs
  2. 将您的当前sled-repo目录移动到安全位置（例如sled-repo.bak）

     $ mv sled-repo sled-repo.bak
     

  3. 将导出的数据库复制到sled-repo

     $ cp -r exports/2023-07-08T22:26:21.194126713Z sled-repo
     

  4. 启动pict-rs

• GET /internal/hashes?{query} 根据提供的查询按最新到最旧的顺序获取一页哈希值。成功时，它将返回以下JSON

  {
      "msg": "ok",
      "page": {
          "limit": 20,
          "current": "some-long-slug-string",
          "next": "some-long-slug-string",
          "prev": "some-long-slug-string",
          "hashes": [{
              "hex": "some-long-hex-encoded-hash",
              "aliases": [
                  "file-alias.png",
                  "another-alias.png",
              ],
              "details": {
                  "width": 1920,
                  "height": 1080,
                  "frames": 30,
                  "content_type": "video/mp4",
                  "created_at": "2022-04-08T18:33:42.957791698Z"
              }
          }]
      }
  }
  

  请注意，此响应中的一些字段是可选的（包括next、prev、current、details和frames）

  可用查询选项

  • empty：这将获取结果的第一页（例如，最新媒体）
  • ?slug={slug} 这将获取结果页面的特定页面。字段 slug 来自页面 JSON 中的 current、next 或 prev 字段
  • ?timestamp={timestamp} 这将获取早于指定时间戳的结果，以便轻松搜索数据。 timestamp 应根据 RFC3339 格式化
  • ?limit={limit} 指定每页返回的结果数量

• POST /internal/prune_missing?force={force} 启动一个后台任务，该任务将检查数据库中的每个哈希值是否有相关的媒体文件，删除任何缺少媒体记录的记录。

  警告：此操作非常具有破坏性。请在调用之前进行备份。

  此端点可以被重复调用以检查准备工作的进度。返回的 progress 值表示已标记为修剪的记录数量。

  可选地，可以将 force 查询参数传递给值 true，以便在当前任务似乎卡住时让 pict-rs 启动另一个任务。

此外，所有端点都支持设置截止日期，在此之后请求将停止处理。要为您的请求启用截止日期，可以将 X-Request-Deadline 标头设置为表示自 UNIX Epoch 以来的纳秒数的 i128 值。计算此值的一个简单方法是使用 time crate 的 OffsetDateTime::unix_timestamp_nanos 方法。例如，

// set deadline of 1ms
let deadline = time::OffsetDateTime::now_utc() + time::Duration::new(0, 1_000);

let request = client
    .get("http://pict-rs:8080/image/details/original/asdfghjkla.png")
    .insert_header(("X-Request-Deadline", deadline.unix_timestamp_nanos().to_string())))
    .send()
    .await;

最后，还有一个可选的 Prometheus 抓取端点，可以通过 PICTRS__METRICS__PROMETHEUS_ADDRESS 配置启用。这将绑定到主 pict-rs 应用程序之外的一个单独端口。有关更多详细信息，请参阅 pict-rs.toml。

管理

备份

pict-rs 维护两个重要的文件夹：sled-repo 目录和 files 目录。 sled-repo 是它存储有关文件元数据的地方，例如：它们的位置、它们的别名、它们处理后的版本的位置、它们的尺寸、MIME 类型等。 files 是它将上传的文件存储在本地文件系统中的位置。

与 files 文件夹相比，sled-repo 文件夹通常很小，备份它只需将其复制到其他位置即可。我建议在 pict-rs 不运行时进行此操作。

如果您无法停止 pict-rs，但想备份数据库，则可以在 Api 中找到的内部端点 /internal/export，用于生成当前数据库的副本，以便轻松备份。

从0.4到0.5迁移指南

注意

如果您正在运行 pict-rs 的旧版本，您需要首先更新到 0.4，然后再继续到 0.5。请参阅 0.3 到 0.4 迁移指南。

概述

在第一次启动0.5版本时，pict-rs将自动将0.4数据库格式迁移到0.5数据库格式。这个过程可能需要一些时间，尤其是如果你从0.3版本之前就开始运行pict-rs。原因是pict-rs现在要求原始文件在数据库中存储相关详细信息记录，而虽然0.3和0.4版本默认会生成这些记录，但在这一标准之前上传的图像可能从未生成过详细信息记录。

升级配置

由于升级可能需要很长时间，因此引入了新的配置选项以尝试提高其速度。

[upgrade]
concurrency = 32

或

PICTRS__UPGRADE__CONCURRENCY=32

或

$ pict-rs run --upgrade-concurrency 32

此值指定pict-rs将同时尝试迁移多少个哈希值。由于此值将增加对Repo和Store的并发连接数，以及可能增加CPU和内存使用，因此在增加之前应仔细考虑。

对于大规模部署，此值可能应该增加到128、256甚至512。默认值为32。

配置更新

以前，pict-rs只有两种文件类别：图像和视频。pict-rs 0.5添加了第三个类别：动画。由于现在显式支持动画文件类型，一些配置选项已移动。

图像更改

动画更改

视频更改

请注意，尽管每种媒体类型现在都有自己的MAX_FILE_SIZE配置，但PICTRS__MEDIA__MAX_FILE_SIZE值仍然存在，作为任何文件类型的全局限制。

除了上述所有配置选项之外，现在还可以为每种图像和动画类型以及视频文件配置单独的质量设置。有关更多信息，请参阅pict-rs.toml文件。

直接升级到Postgres

pict-rs支持在升级期间直接迁移到postgres repo。为了执行此操作，需要配置postgres repo并指定old_repo。该old_repo部分仅包含您的0.4配置中repo部分的path。

示例

[old_repo]
path = '/mnt/sled-repo'

[repo]
type = 'postgres'
url = 'postgres://user:password@host:5432/db'

或使用环境变量

PICTRS__OLD_REPO__PATH=/mnt/sled-repo
PICTRS__REPO__TYPE=postgres
PICTRS__REPO__URL=postgres://user:password@host:5432/db

设置这些变量后，即可启动0.5并自动执行迁移。

文件系统到对象存储迁移

在运行此命令之前，请确保备份sled-repo目录！！！将迁移到对象存储会更新数据库，如果您需要因任何原因回滚，则需要备份。

可以迁移到对象存储。如果在云环境中托管，这可能很有用，因为对象存储通常比块存储便宜得多。

对象存储需要一些配置选项。我将尝试解释。

• 端点：这是对象存储可用的URL。通常这个URL看起来像这样 https://<bucket-name>.<region>.s3.example.com，但有时它可能看起来像 https://<region>.s3.example.com 或只是 https://s3.example.com
• bucket-name：这是对象将驻留的“bucket”的名称。bucket必须已经存在，迁移才能工作 - pict-rs不会自己创建bucket。您需要提前使用存储提供商创建bucket。
• region：这是bucket所在的“位置”。根据您的云提供商，这可能没有意义，但它总是必需的。
• access-key：这是云提供商将为您提供以访问bucket的秘密。
• secret-key：这是云提供商将为您提供以访问bucket的第二个秘密。

此外，还有一个命令行参数可以设置以更改迁移的默认并发级别。pict-rs将尝试一次迁移32个散列，但对于大型部署，尝试增加此值可能是有益的。将其设置为128、256甚至512可能很有用。请注意，此值越大，对对象存储提供商的并发连接就越多。

命令看起来可能如下所示

$ pict-rs \
    migrate-store \
        --concurrency 32 \
    filesystem \
        -p /path/to/files \
    object-storage \
        -e https://object-storage-endpoint \
        -b bucket-name \
        -r region \
        -a access-key \
        -s secret-key \
    sled \
        -p /path/to/sled-repo

如果您使用默认路径运行docker容器，它可以简化为以下内容

$ pict-rs \
    migrate-store \
    filesystem \
    object-storage \
        -e https://object-storage-endpoint \
        -b bucket-name \
        -r region \
        -a access-key \
        -s secret-key

此命令必须在pict-rs离线时运行。

如果您使用docker-compose运行，它可能看起来如下所示

$ sudo docker compose stop pictrs # stop the pict-rs container
$ sudo docker compose run pictrs sh # launch a shell in the pict-rs container
> pict-rs --version # verify pict-rs version is recent (should probably be 0.4.0 or later)
> pict-rs \
    migrate-store \
    filesystem \
    object-storage \
        -e endpoint \
        -b bucket \
        -r region \
        -a -access-key \
        -s secret-key
> exit
$ vi docker-compose.yml # edit the docker-compose yaml however you like to edit it, make sure all the variables described below are set
$ sudo docker compose up -d pictrs # start pict-rs again after the migration. Note that this is not 'docker compose start'. using the `up` subcommand explicitly reloads configurations

根据您的docker或docker-compose版本，您可能需要使用以下命令打开shell

$ sudo docker-compose run -i pictrs sh

以下是基于我自己的对象存储的示例，我在kubernetes上自己托管，使用garage

$ pict-rs \
    migrate-store \
    filesystem \
    object-storage \
        --use-path-style \
        -e http://garage-daemon.garage.svc:3900 \
        -b pict-rs \
        -r garage \
        -a <redacted> \
        -s <redacted>

以下是基于backblaze b2用户的配置示例；

$ pict-rs \
    migrate-store \
    filesystem \
    object-storage \
        --use-path-style \
        -e https://s3.us-east-005.backblazeb2.com \
        -r us-east-005 \
        -b SitenamePictrs \
        -a redacted \
        -s redacted

迁移完成后，请更新pict-rs配置以使用对象存储。如果您使用环境变量配置，请确保以下设置

• PICTRS__STORE__TYPE=object_storage
• PICTRS__STORE__ENDPOINT=https://object-storage-endpoint
• PICTRS__STORE__BUCKET_NAME=bucket-name
• PICTRS__STORE__REGION=region
• PICTRS__STORE__USE_PATH_STYLE=false（如果您的对象存储需要路径样式访问，请将其设置为true）
• PICTRS__STORE__ACCESS_KEY=access-key
• PICTRS__STORE__SECRET_KEY=secret-key

如果您使用配置文件，它将是这样的

[store]
type = "object_storage"
endpoint = "https://object-storage-endpoint"
bucket_name = "bucket-name"
region = "region"
use_path_style = false # Set to true if your object storage requires path style access
access_key = "access-key"
secret_key = "secret-key"

迁移故障排除

如果您在尝试启动迁移时看到如下错误

   0: IO error: could not acquire lock on "/mnt/sled-repo/v0.4.0-alpha.1/db": Os { code: 11, kind: WouldBlock, message: "Resource temporarily unavailable" }

这意味着pict-rs无法打开其数据库。这可能是由于另一个pict-rs副本正在运行。在迁移之前，请确保停止所有运行的pict-rs进程。

如果您尝试迁移并看到“Failed moving file. Retrying +1”，请不要取消迁移。让它达到10次重试。之后将打印出更具有意义的错误。以下是一些错误及其原因的示例

错误

   0: Error in store
   1: Error in object store
   2: Invalid status: 400 Bad Request
   2: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <Error>
          <Code>InvalidRequest</Code>
          <Message>Authorization header's Credential is malformed</Message>
      </Error>

原因：区域设置不正确。另外，使用了路径样式端点而没有传递 --use-path-style

错误

   0: Error in store
   1: Error in object store
   2: Invalid status: 403 Forbidden
   2: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <Error>
          <Code>InvalidAccessKeyId</Code>
          <Message>Malformed Access Key Id</Message>
      </Error>

原因：access key设置不正确

如果您在将现有文件迁移到对象存储之前启用了对象存储，这些迁移命令可能会无限期地重试文件迁移。为了成功解决这个多存储问题，已在 --skip-missing-files 子命令中添加了标志。这将告诉 pict-rs 如果文件返回某种形式的“未找到”错误，则不要重试迁移该文件。

$ pict-rs \
    migrate-store --skip-missing-files \
    filesystem -p /path/to/files \
    object-storage \
        -e https://object-storage-endpoint \
        -b bucket-name \
        -r region \
        -a access-key \
        -s secret-key \
    sled \
        -p /path/to/sled-repo

如果您在使用 pict-rs 上传到对象存储时遇到问题，请检查以下事项：您的对象存储是否需要路径风格访问？一些对象存储提供商，如 Contabo，不支持虚拟托管存储桶。以下是一个基本示例

路径风格 URL：https://region.example.com/bucket-name 虚拟主机风格 URL：https://bucket-name.region.example.com

如果确实需要使用路径风格，您的命令可能看起来像这样

$ pict-rs \
    migrate-store \
    filesystem -p /path/to/files \
    object-storage \
        --use-path-style \
        -e https://object-storage-endpoint \
        -b bucket-name \
        -r region \
        -a access-key \
        -s secret-key \
    sled \
        -p /path/to/sled-repo

此外，一些提供商可能要求您在端点 URL 中包含 region：例如 https://region.host.com，而其他提供商可能只需要顶级端点：例如 https://example.com。

请检查对象存储提供商的文档，以确保您设置了正确的值。

Sled到Postgres迁移

如果您在没有迁移到 postgres 的情况下升级到 0.5，您可以使用内置的迁移工具事后迁移到 postgres。在运行迁移之前，请确保您为 pict-rs 准备了一个 postgres 角色和数据库名称。pict-rs 连接到新数据库时，首先要做的事情是尝试添加 pgcrypto 扩展，如果为 pict-rs 创建的角色没有这个权限，则迁移将失败。

迁移命令相当简单。只需要提供现有存储库的路径和新的存储库 URL。

$ pict-rs \
    migrate-repo \
    sled -p /path/to-/sled-repo \
    postgres -u postgres://user:password@host:5432/db

如果您使用docker-compose运行，它可能看起来如下所示

$ sudo docker compose stop pictrs # stop the pict-rs container
$ sudo docker compose run pictrs sh # launch a shell in the pict-rs container
> pict-rs --version # verify pict-rs version is recent (should probably be 0.5.0 or later)
> pict-rs \
    migrate-repo \
    sled -p /mnt/sled-repo \
    postgres -u postgres://user:password@host:5432/db
> exit
$ vi docker-compose.yml # edit the docker-compose yaml however you like to edit it, make sure all the variables described below are set
$ sudo docker compose up -d pictrs # start pict-rs again after the migration. Note that this is not 'docker compose start'. using the `up` subcommand explicitly reloads configurations

此命令必须在pict-rs离线时运行。

这次迁移应该相当快，因为没有实际文件被移动。迁移完成后，确保 pict-rs 配置为使用 postgres 存储库，然后重新启动。

示例

[repo]
type = 'postgres'
url = 'postgres://user:password@host:5432/db'

或

PICTRS__REPO__TYPE=postgres
PICTRS__REPO__URL=postgres://user:password@host:5432/db

开发

pict-rs 有一些需要安装才能正常运行的原生依赖项。目前这些如下

• imagemagick 7.1.1（尽管 7.0 和 7.1.0 也可能工作）
• ffmpeg 6（尽管 5 也可能工作）
• exiftool 12.62（尽管 12.50 或更新版本也可能工作）

此外，pict-rs 在编译步骤需要 protobuf 编译器以支持 tokio-console，这是一个运行时调试工具。

使用您喜欢的包管理器安装这些依赖项应该足够了。以下是开发和使用 pict-rs 二进制文件的几种有趣方式。

Nix开发

我本人使用 nix 进行开发。提供的 flake.nix 文件应该足以在安装 nix 的任何 Linux 发行版上创建 pict-rs 的开发环境。

使用direnv和nix-direnv

使用这些工具，在进入 pict-rs 目录时可以自动加载 pict-rs 开发环境。

设置（仅一次）

$ echo 'use flake' > .envrc
$ direnv allow

运行

$ cargo run -- -c dev.toml run

仅使用Nix

$ nix develop
$ cargo run -- -c dev.toml run

Docker开发

以前，我已经在包含正确依赖项的容器中运行 pict-rs。下面列出的两个选项是我亲自尝试过的。

使用Arch

此选项不需要太多配置，只需在容器内编译二进制文件并运行即可

$ cargo build
$ sudo docker run --rm -it -p 8080:8080 -v "$(pwd):/mnt" archlinux:latest
> pacman -Syu imagemagick ffmepg perl-image-exiftool
> PATH=$PATH:/usr/bin/vendor_perl /mnt/target/debug/pict-rs --log-targets debug run

使用Alpine

此选项需要安装 cargo-zigbuild。Cargo Zigbuild 是一个工具，它使用 Zig 的链接器链接 Rust 二进制文件，从而可以轻松地针对许多目标进行交叉编译。Zig 在无缝交叉编译方面投入了大量努力，能够从 Rust 中利用这些工作非常令人高兴。

$ cargo zigbuild --target=x86_64-unknown-linux-musl
$ sudo docker run --rm -it -p 8080:8080 -v "$(pwd):/mnt" alpine:3.18
> apk add imagemagick ffmpeg exiftool
> /mnt/target/x86_64-unknown-linux-musl/debug/pict-rs --log-targets debug run

贡献

如果您发现任何问题，请随时提交问题。请注意，任何贡献的代码都将根据 AGPLv3 许可。

常见问题解答

问题：pict-rs 是否无状态？

回答：可以。默认情况下，pict-rs 使用磁盘存储文件以及名为 sled 的磁盘键值存储来存储元数据。这是为了便于小型配置的部署。如果需要 pict-rs 不保留任何本地状态（除 /tmp 外），可以配置它使用对象存储来存储文件和使用 Postgres 来存储元数据。

问题：我能否使用与 pict-rs 不同的数据库？

回答：可以。pict-rs 支持 sled 和 postgres 来存储元数据。将来我也可能支持 BonsaiDB。如果您希望 pict-rs 支持其他数据库，请随意提交更改 :)

问题：我如何提交更改？

回答：如果您想为 pict-rs 做贡献，可以将您的代码推送到您选择的公共 git 主机，并通过 matrix 或电子邮件通知我。我可以从那里拉取和合并您的更改到这个仓库中。

或者，您也可以通过电子邮件将补丁发给我。

我不会在我的 forgejo 服务器上创建额外的账户，抱歉了。

问题：我想用 yaml 而不是 toml 来配置它？

回答：这不是一个问题，但您可以使用 json、hjson、yaml、ini 或 toml 来配置 pict-rs。将配置写入其他格式是留给读者的练习。

问题：我如何捐赠给 pict-rs？

回答：您不需要。我通过做其他工作来赚钱。不要给我不需要的钱。

常见问题

在某些情况下，pict-rs 可能会崩溃并且无法重新启动。最常见的原因是文件系统达到 100%，pict-rs 无法写入磁盘，但这也可能在不幸的时刻杀死 pict-rs 时发生。如果发生这种情况，解决方案是首先为您的服务器获取更多磁盘空间，然后查找 sled-repo 目录中的 pict-rs。很可能是 pict-rs 创建了一个名为 snap.somehash.generating 的零大小文件。删除该文件并重新启动 pict-rs。

当使用提供的 docker 容器运行时，pict-rs 可能会因为权限错误而无法启动，显示“权限被拒绝”的 I/O 错误。这很可能意味着 pict-rs 的卷不是由正确的用户拥有的。将 pict-rs 卷的所有权更改为 991:991 应该解决这个问题。

许可证

版权 © 2022 Riley Trautman

pict-rs 是自由软件：您可以在自由软件基金会发布的 GNU 通用公共许可证的条款下重新分配它和/或修改它，无论是许可证的第 3 版，还是（根据您的选择）任何后续版本。

pict-rs 是希望它会有用而发布的，但没有任何保证；甚至没有关于适销性或特定用途的隐含保证。有关详细信息，请参阅 GNU 通用公共许可证。本文件是 pict-rs 的一部分。

您应该已经随 pict-rs 收到了一份 GNU 通用公共许可证的副本。如果没有，请参阅 https://gnu.ac.cn/licenses/。