身份验证后端（共享 SQL）

身份验证状态——已注册的用户及其持有者令牌——是每个实例的磁盘状态。默认情况下，用户存储在 htpasswd 文件中，令牌存储在本地 SQLite 数据库中（参见 auth），因此两个 pnpr 副本无法看到彼此的账户。

🌐 Auth state — the registered users and their bearer tokens — is per-instance disk state. By default users live in an htpasswd file and tokens in a local SQLite database (see auth), so two pnpr replicas don't see each other's accounts.

添加一个 backend: 块会将两者移动到一个共享的 SQL 数据库中，因此多个无状态副本共享一组一致的登录信息和令牌——这是水平扩展 pnpr 的身份验证部分。配置文件中只能选择一个后端。

🌐 Adding a backend: block moves both into one shared SQL database, so several stateless replicas share a consistent set of logins and tokens — the auth half of running pnpr horizontally scaled. Only one backend may be selected in a config file.

数据库驱动是通过 Cargo 特性控制的：

🌐 Database drivers are Cargo-feature gated:

后端	配置键	Cargo 功能
libsql / Turso	`backend.libsql`	`backend-libsql`（默认启用）
PostgreSQL	`backend.postgres` 或 `backend.postgresql`	`backend-postgres`
兼容 MySQL	`backend.mysql`	`backend-mysql`

对于 PostgreSQL 或 MySQL 支持，请使用匹配的 Cargo 功能构建 pnpr，例如 cargo build -p pnpr --features backend-postgres。

🌐 For PostgreSQL or MySQL support, build pnpr with the matching Cargo feature, for example cargo build -p pnpr --features backend-postgres.

tip

令牌查找发生在请求热路径上，因此数据库从服务器来看应具有低延迟。

🌐 Token lookups happen on the request hot path, so the database should be low-latency from the server.

libsql / Turso

storage: ./storage

backend:
  libsql:
    # libsql/Turso database URL. `libsql://…` for Turso, or
    # `http://127.0.0.1:8080` for a local `sqld`.
    url: ${PNPR_LIBSQL_URL}
    # Bearer token for the database. Omit for an unauthenticated local `sqld`.
    authToken: ${PNPR_LIBSQL_TOKEN}

键	必填	描述
`url`	是	数据库 URL — `libsql://<db>.turso.io`（Turso）或 `http://<host>:<port>`（自托管 `sqld`）。
`authToken`	否	数据库的 Bearer 令牌。本地未认证 `sqld` 可省略。
`replicaPath`	否	本地嵌入式副本的路径。设置后，读取（令牌查找）将访问此本地文件而非网络请求；写入仍发送到主库。未设置 ⇒ 每次读取都是远程查询。
`syncIntervalSecs`	否	嵌入式副本从主库拉取的频率（秒）。仅在 `replicaPath` 时有意义；限定读取数据的延迟时间（令牌撤销延迟）。`0` 可禁用后台同步。默认值为 `60`。

对于远程主节点（例如 Turso），从本地副本提供读取服务：

🌐 For a remote primary (e.g. Turso), serve reads from a local replica:

backend:
  libsql:
    url: ${PNPR_LIBSQL_URL}
    authToken: ${PNPR_LIBSQL_TOKEN}
    replicaPath: ./auth-replica.db
    syncIntervalSecs: 60

权衡在于读取的新鲜度：嵌入式副本只有在下一次后台同步后才会反映另一个副本的写入（在其他地方发出的或撤销的令牌），因此较低的 syncIntervalSecs 意味着较少的撤销延迟。省略 replicaPath 可始终直接读取主节点。

🌐 The trade-off is read freshness: an embedded replica reflects another replica's writes (a token issued or revoked elsewhere) only after the next background sync, so a lower syncIntervalSecs means less revocation lag. Omit replicaPath to always read the primary directly.

PostgreSQL

backend:
  postgres:
    url: ${PNPR_POSTGRES_URL}
    maxConnections: 16
    timeout: 30s
    startupTimeout: 5m

MySQL

backend:
  mysql:
    url: ${PNPR_MYSQL_URL}
    maxConnections: 16
    timeout: 30s
    startupTimeout: 5m

键	必填	描述
`url`	是	驱动连接 URL，例如 `postgres://user:pass@host/db` 或 `mysql://user:pass@host/db`。
`maxConnections`	否	后端连接池的最大连接数。省略以使用驱动的默认值。
`timeout`	否	请求路径认证数据库的截止时间。默认值为 `30s`。
`startupTimeout`	否	启动连接和模式设置的截止时间。默认值为 `5m`。

当 backend: 块缺失时，认证仍然保存在本地磁盘，并且 auth.htpasswd / auth.tokens 设置照常适用。无论哪种情况，auth.htpasswd.max_users 注册上限都会得到遵守。省略 max_users 和 max_users: -1 都会禁用自助注册；设置非负上限可允许新用户注册。

🌐 When the backend: block is absent, auth stays on local disk and the auth.htpasswd / auth.tokens settings apply as before. The auth.htpasswd.max_users registration cap is honored either way. Omitted max_users and max_users: -1 both disable self-registration; set a non-negative cap to let new users register.

libsql / Turso​

PostgreSQL​

MySQL​

libsql / Turso

PostgreSQL

MySQL