配置
pwikit 从命令行参数、环境变量与 pwikit.toml 文件读取设置。本文列出全部设置。pwikit 的安装与运行见部署。
设置的来源
pwikit.toml 位于数据目录中；除非通过 -data-dir 或 PWIKIT_DATA_DIR 另行指定，数据目录即可执行文件所在的目录。首次执行 pwikit createsite 或 pwikit serve 时会写入该文件，内容为全部设置均被注释掉的模板。已存在的文件不会被覆盖。在 Linux 与 macOS 上，该文件创建时仅所有者可读。
同一设置在多处指定时，按以下顺序先找到者生效：
- 命令行参数
- 环境变量
pwikit.toml- 默认值
空的环境变量，以及 pwikit.toml 中的空字符串，均视为未设置。并非每项设置都能在上述三处指定，各项设置可指定的位置见下文各表。
pwikit 只在启动时读取设置。更改任何设置后，请重新启动 pwikit。
pwikit serve 读取整个文件。createsite、site、admin、user、seed、import、reindex、migrate、backup create 与 backup restore 命令只读取 database，且仅在未指定 -database 与 DATABASE_URL 时读取。pwikit service install 读取整个文件，用于检查设置并确定要开放的防火墙端口。
环境变量不会传递给作为系统服务安装的 pwikit。对于服务，请使用 pwikit.toml，或在安装时将参数放在 -- 之后。
模板
生成的 pwikit.toml 列出全部设置，每项均已注释并附有简短说明，删去行首的 # 即可启用。文件由顶层的 database 与 [server]、[tls]、[mail]、[analytics]、[update] 各节组成，各项设置见下文。生成的文件如下：
# Settings for pwikit. A line starting with # is an example and changes nothing
# until the # is taken away.
# A flag on the command line wins over this file, and so does an environment variable.
# Restart pwikit after changing anything here.
# A PostgreSQL of your own. Left unset, pwikit runs the one it carries.
# database = "postgres://user:password@127.0.0.1:5432/pwikit"
[server]
# listen = "127.0.0.1:8080"
# trusted_proxies = ["127.0.0.1"]
# upload_limit = "4GB"
# storage_limit = "0"
[tls]
# Left unset, pwikit serves HTTPS on ports 80 and 443 with certificates from
# Let's Encrypt once a site is bound to a public domain, and plain HTTP on
# 127.0.0.1:8080 until then. Setting listen or trusted_proxies means a proxy sits
# in front, and turns that off.
# off serves plain HTTP, file uses the certificate below, auto always obtains one.
# mode = "auto"
# listen = ":443"
# cert = "/path/to/fullchain.pem"
# key = "/path/to/privkey.pem"
# acme_email = "you@example.com"
# acme_directory = ""
[mail]
# smtp sends mail, console writes it into the log instead.
# engine = "smtp"
# host = "smtp.example.com"
# port = 587
# username = "wiki@example.com"
# password = ""
# use_tls = true
# implicit_tls = false
# from = "wiki@example.com"
[analytics]
# google_tag_id = ""
[update]
# pwikit installed as a system service looks for a new release every hour and
# installs it by itself inside the window below.
# auto = true
# Whether every visitor sees the banner announcing an automatic update, or only
# the people who can open the admin panel.
# public_banner = true
# false stops pwikit from asking for new releases at all.
# check = true
# The hours in which updates are installed, read in time_zone.
# window = "03:00-05:00"
# The time zone the window is read in, such as "Asia/Shanghai". Empty uses this
# machine's time zone.
# time_zone = ""
# How long a release must have been out before it is installed automatically.
# 0s installs it in the next window.
# min_age = "0s"
# A mirror to download from when GitHub cannot be reached. Use only a mirror you trust.
# pwikit update mirror <address> sets this line.
# mirror = ""出现 pwikit 无法识别的键时，启动会中止，错误信息会指出该键：
pwikit: /opt/pwikit/pwikit.toml has settings pwikit does not know: server.lisen值的类型错误（例如写成 port = "587" 而非 port = 587）同样会中止启动。
顶层
| 键 | 类型 | 默认值 | 命令行参数 | 环境变量 | 含义 |
|---|---|---|---|---|---|
database | 字符串 | 空：使用内置 PostgreSQL | -database | DATABASE_URL | 自有 PostgreSQL 的连接字符串，例如 postgres://user:password@127.0.0.1:5432/pwikit。见部署。 |
[server]
| 键 | 类型 | 默认值 | 命令行参数 | 环境变量 | 含义 |
|---|---|---|---|---|---|
listen | 字符串 | 127.0.0.1:8080；启用 HTTPS 时为 :80 | -listen | 无 | 纯 HTTP 的监听地址。启用 HTTPS 时，该端口将请求重定向到 HTTPS。设置此项会停用自动 HTTPS。 |
trusted_proxies | 字符串数组 | 空 | -trusted-proxies | 无 | 反向代理的地址或 CIDR 网段，例如 ["127.0.0.1", "10.0.0.0/8"]。仅来自这些地址的请求可以设置 X-Forwarded-For 与 X-Forwarded-Proto。命令行参数使用逗号分隔的列表。设置此项会停用自动 HTTPS。 |
upload_limit | 字符串 | "0"：不限制 | -upload-limit | MEDIA_UPLOAD_LIMIT | 当前附加在页面上的文件总大小上限，按本实例的所有站点合计。 |
storage_limit | 字符串 | "0"：不限制 | -storage-limit | ABSOLUTE_MEDIA_UPLOAD_LIMIT | 所有已存储文件的总大小上限，包括已删除但仍保留在磁盘上的文件，按本实例的所有站点合计。 |
大小的写法为整数后接可选单位：B、KB、MB、GB 或 TB，不区分大小写。1 KB 为 1024 字节。不带单位的数字表示字节数。在 pwikit.toml 中，大小须写成带引号的字符串，例如 upload_limit = "4GB"。上传会导致超出任一上限时，该上传将被拒绝。
[tls]
| 键 | 类型 | 默认值 | 命令行参数 | 环境变量 | 含义 |
|---|---|---|---|---|---|
mode | 字符串 | 自动选择 | -tls | PWIKIT_TLS | off、file 或 auto。见「HTTPS 模式的选择」。 |
listen | 字符串 | :443 | -tls-listen | PWIKIT_TLS_LISTEN | HTTPS 的监听地址。 |
cert | 字符串 | 空 | -tls-cert | PWIKIT_TLS_CERT | PEM 格式的证书链，用于 file 模式。 |
key | 字符串 | 空 | -tls-key | PWIKIT_TLS_KEY | PEM 格式的私钥，用于 file 模式。 |
acme_email | 字符串 | 空 | -acme-email | PWIKIT_ACME_EMAIL | 向证书颁发机构登记的联系地址。可选。 |
acme_directory | 字符串 | 空：使用 Let's Encrypt | -acme-directory | PWIKIT_ACME_DIRECTORY | 其他 ACME 证书颁发机构的目录 URL，例如 Let's Encrypt 测试环境目录 https://acme-staging-v02.api.letsencrypt.org/directory。 |
HTTPS 模式的选择
pwikit 在启动时按以下顺序决定提供服务的方式：
- 指定
-dev时，pwikit 在127.0.0.1:8080或-listen指定的端口上提供纯 HTTP。环境变量与pwikit.toml中的mode、listen与trusted_proxies均被忽略。见部署。 - 如果通过命令行参数、环境变量或
pwikit.toml设置了mode，则使用该模式：off：在listen上提供纯 HTTP，默认为127.0.0.1:8080。file：在[tls] listen上使用cert与key指定的证书提供 HTTPS。[server] listen（默认为:80）将请求重定向到 HTTPS。auto：在[tls] listen上提供 HTTPS，并通过 ACME 为各站点的域名与文件域名获取证书。[server] listen（默认为:80）将请求重定向到 HTTPS，并响应证书颁发机构的验证请求。
- 如果未设置
mode，但设置了listen或trusted_proxies，则模式为off。设置其中任一项，即表示由反向代理处理 HTTPS。 - 否则，pwikit 检查所有站点的域名与文件域名。只要有一个是公网域名，模式即为
auto，pwikit 监听:80与[tls] listen；否则模式为off，监听127.0.0.1:8080。
IP 地址、包含端口的名称、不含点号的名称，以及等于或以 localhost、localdomain、local、test、example、invalid、internal、lan、home.arpa、example.com、example.net、example.org 结尾的名称，均不属于公网域名。
mode 接受 off、file 与 auto，不区分大小写。其他任何值都会中止启动。file 模式下未同时设置 cert 与 key，同样会中止启动。
[mail]
邮件设置没有对应的命令行参数。环境变量优先于 pwikit.toml。
| 键 | 类型 | 默认值 | 环境变量 | 含义 |
|---|---|---|---|---|
engine | 字符串 | smtp | EMAIL_ENGINE | smtp 通过 host 发送邮件。console 将每封邮件写入日志而不发送。pwikit.toml 中的其他值会中止启动。 |
host | 字符串 | 空 | EMAIL_HOST | SMTP 服务器。为空时，邮件写入日志而不发送。 |
port | 整数 | 587 | EMAIL_PORT | SMTP 端口。465 端口始终从连接开始即使用加密连接，效果等同于同时开启 use_tls 与 implicit_tls。 |
username | 字符串 | 空 | EMAIL_USERNAME | 登录 SMTP 服务器所用的账户。为空时，pwikit 不进行登录。 |
password | 字符串 | 空 | EMAIL_PASSWORD | username 的密码。 |
use_tls | 布尔值 | false | EMAIL_USE_TLS | 连接后通过 STARTTLS 切换到 TLS。 |
implicit_tls | 布尔值 | false | EMAIL_IMPLICIT_TLS | 从连接开始即使用 TLS。 |
from | 字符串 | 空 | EMAIL_DEFAULT_FROM | 发件人地址。必填：未设置时发送会失败。 |
对于 EMAIL_USE_TLS 与 EMAIL_IMPLICIT_TLS，值为 true 时开启该设置，其他任何非空值均为关闭。
pwikit 只通过加密连接发送密码，或将密码发送给本机（localhost）上的邮件服务器。如果远程邮件服务器要求登录，请开启 use_tls 或 implicit_tls。
在 Linux 与 macOS 上，如果 pwikit.toml 中包含 password，且本机其他账户可以读取该文件，pwikit 会在启动时记录以下警告：
pwikit.toml holds the mail password and other accounts on this machine can read it请执行 chmod 600 pwikit.toml，使该文件仅所有者可读。
[update]
| 键 | 类型 | 默认值 | 环境变量 | 含义 |
|---|---|---|---|---|
auto | 布尔值 | true | PWIKIT_UPDATE_AUTO | 以系统服务方式运行时，自动安装新版本。 |
public_banner | 布尔值 | true | PWIKIT_UPDATE_PUBLIC_BANNER | 自动更新前的 10 分钟内，向所有访问者显示更新横幅。为 false 时只在管理后台提示。 |
check | 布尔值 | true | PWIKIT_UPDATE_CHECK | 检查新版本。为 false 时既不检查也不提示，pwikit 不再访问 GitHub 或镜像。 |
window | 字符串 | 03:00-05:00 | PWIKIT_UPDATE_WINDOW | 自动安装新版本的时段，按 time_zone 计算。检查不受此限制，每小时一次。可跨越午夜，至少 11 分钟。 |
time_zone | 字符串 | 空 | PWIKIT_UPDATE_TIME_ZONE | window 所用的时区。留空时使用服务器的时区，设置后覆盖它。填写时区数据库中的名称，如 Asia/Shanghai、Asia/Tokyo；不接受 UTC+9 这种写法。需要固定时差时可写 Etc/GMT-9，注意正负号相反，它表示 UTC+9。 |
min_age | 字符串 | 0s | PWIKIT_UPDATE_MIN_AGE | 版本发布满这么久才会自动安装，如 24h。为 0s 时发现后即安排到最近的更新时段。 |
mirror | 字符串 | 空 | PWIKIT_UPDATE_MIRROR | GitHub 无法访问时使用的镜像地址。 |
对应的命令行参数为 -update-auto、-update-public-banner、-update-check、-update-window、-update-time-zone、-update-min-age 与 -update-mirror。更新的时间安排、横幅与回档见更新与回档。
[analytics]
| 键 | 类型 | 默认值 | 环境变量 | 含义 |
|---|---|---|---|---|
google_tag_id | 字符串 | 空 | GOOGLE_TAG_ID | Google 代码（Google tag）ID。设置后，本实例所有站点的页面都会加入 Google 代码。 |
此设置没有对应的命令行参数。环境变量优先于 pwikit.toml。
pwikit.toml 之外的设置
以下设置仅作为 pwikit serve 的命令行参数存在，其中部分也可通过环境变量指定。
| 命令行参数 | 环境变量 | 默认值 | 含义 |
|---|---|---|---|
-data-dir | PWIKIT_DATA_DIR | 可执行文件所在的目录 | 数据目录。所有使用数据目录的命令均接受此参数。 |
-secret-key | SECRET_KEY | secrets/session-key 的内容 | 用于签名登录会话与邮件中链接的密钥。 |
-static-dir | 无 | 内置资源 | 改为从该目录提供页面静态资源（样式表、脚本、字体与图片），而不使用内置的副本。仅在修改网页界面时需要。见部署。 |
-log-file | 无 | 标准错误 | 追加写入日志的文件。达到 10 MB 时重命名为 <文件名>.1，最多保留 5 个旧文件。 |
-sidecar | PWIKIT_FTML_SIDECAR | 无 | ftml sidecar 程序的路径。仅未内置维基语法渲染器的 pwikit 版本需要。 |
-no-migrate | 无 | 关闭 | 启动时不应用待应用的数据库变更。 |
-dev | 无 | 关闭 | 开发模式。见部署。 |
secrets 目录
pwikit 在数据目录下的 secrets/ 中生成以下文件：
| 文件 | 内容 |
|---|---|
session-key | 用于签名登录会话与邮件中链接的密钥。未指定 -secret-key 或 SECRET_KEY 时，在首次启动时生成。替换或删除该文件会使所有用户退出登录，并使已通过邮件发出的链接失效。 |
postgres-password | 仅限 Windows 上使用内置 PostgreSQL 的情况。内置数据库的密码。 |
certs/ | auto 模式下的证书以及证书颁发机构账户密钥。删除后，pwikit 会重新申请证书；证书颁发机构对同一证书的签发频率有限制。 |
注意 请勿删除或修改
secrets/postgres-password。否则 pwikit 会生成一个现有数据库不接受的新密码，从而无法再连接数据库。
环境变量
| 变量 | 对应设置 | 读取者 |
|---|---|---|
PWIKIT_DATA_DIR | 数据目录 | 所有使用数据目录的命令 |
DATABASE_URL | database | serve、createsite、site、admin、user、seed、import、reindex、migrate、backup create、backup restore、update |
SECRET_KEY | -secret-key | serve |
PWIKIT_FTML_SIDECAR | -sidecar | serve、render、reindex |
MEDIA_UPLOAD_LIMIT | [server] upload_limit | serve |
ABSOLUTE_MEDIA_UPLOAD_LIMIT | [server] storage_limit | serve |
PWIKIT_TLS | [tls] mode | serve、service install |
PWIKIT_TLS_LISTEN | [tls] listen | serve、service install |
PWIKIT_TLS_CERT | [tls] cert | serve |
PWIKIT_TLS_KEY | [tls] key | serve |
PWIKIT_ACME_EMAIL | [tls] acme_email | serve |
PWIKIT_ACME_DIRECTORY | [tls] acme_directory | serve |
EMAIL_ENGINE | [mail] engine | serve |
EMAIL_HOST | [mail] host | serve |
EMAIL_PORT | [mail] port | serve |
EMAIL_USERNAME | [mail] username | serve |
EMAIL_PASSWORD | [mail] password | serve |
EMAIL_USE_TLS | [mail] use_tls | serve |
EMAIL_IMPLICIT_TLS | [mail] implicit_tls | serve |
EMAIL_DEFAULT_FROM | [mail] from | serve |
GOOGLE_TAG_ID | [analytics] google_tag_id | serve |
PWIKIT_UPDATE_AUTO | [update] auto | serve、update |
PWIKIT_UPDATE_PUBLIC_BANNER | [update] public_banner | serve、update |
PWIKIT_UPDATE_CHECK | [update] check | serve、update |
PWIKIT_UPDATE_WINDOW | [update] window | serve、update |
PWIKIT_UPDATE_TIME_ZONE | [update] time_zone | serve、update |
PWIKIT_UPDATE_MIN_AGE | [update] min_age | serve、update |
PWIKIT_UPDATE_MIRROR | [update] mirror | serve、update |
PWIKIT_DATABASE_PASSWORD_FILE | 数据库密码所在的文件。连接字符串中没有密码时，从该文件读取 | 所有连接数据库的命令 |
PWIKIT_CONTAINER | 表示 pwikit 运行在容器中，不自动更新。官方镜像已设置 | serve、update、service install |
LISTEN_PID、LISTEN_FDS、LISTEN_FDNAMES | 由 systemd 移交的监听套接字 | serve |
SUDO_USER | 未指定 -user 时服务所用的账户 | Linux 与 macOS 上的 service install |
SUDO_USER 与三个 LISTEN_ 变量分别由 sudo 与 systemd 设置，请勿手动设置。
由 systemd 移交的套接字
systemd 以套接字激活方式启动 pwikit 时，pwikit 使用收到的套接字，而不自行打开监听地址。请在套接字单元中通过 FileDescriptorName= 将套接字命名为 http 与 https。未命名的套接字按顺序使用：第一个用于纯 HTTP，第二个用于 HTTPS。HTTPS 模式仍按上文所述根据设置选择。pwikit service install 不使用套接字激活。