命令行
ProjectWikit 在浏览器之外的所有操作都通过 pwikit 可执行文件的子命令完成：
pwikit <command> [options]参数以一个短横线开头（-name value 或 -name=value），也可使用两个短横线。布尔参数只需写出参数名即可启用（如 -force）。在任意命令后加 -h 可列出其参数；单独执行命令组（如 pwikit backup）可列出其子命令。
本文示例直接写作 pwikit，这要求 pwikit 已经装好。装好之前，请在 pwikit 所在目录中写作 ./pwikit（Windows 为 .\pwikit.exe）。
| 命令 | 用途 |
|---|---|
serve | 运行 Web 服务器 |
createsite | 创建站点 |
site list | 列出站点及其域名 |
site rebind | 将站点改绑到其他域名 |
admin create | 创建首个管理员，或接管导入的账号 |
admin grant | 授予现有账号全部权限 |
admin revoke | 收回账号的全部权限 |
user merge | 将两个账号合并为一个 |
seed | 写入初始页面 |
import | 从 wikitCLI 备份导入 Wikidot 站点 |
reindex | 将站点的每个页面重新写入搜索索引 |
backup create | 备份整个实例或单个站点 |
backup list | 列出 backups/ 中的备份 |
backup verify | 校验备份文件 |
backup restore | 恢复备份 |
service | 安装、启动、停止和移除系统服务 |
path | 让 pwikit 可以在任意目录直接输入 |
update | 安装新版本、回档，或管理自动更新 |
migrate status | 显示数据库已应用的结构迁移 |
migrate up | 应用缺失的结构迁移 |
render | 在终端中渲染维基语法 |
modules | 列出 pwikit 可识别的 [[module]] 名称 |
version | 显示当前版本 |
help | 显示命令列表 |
通用参数
数据目录
所有状态均保存在数据目录中：pwikit.toml、files/、secrets/、pgdata/、backups/、logs/ 等。pwikit 按以下顺序确定数据目录：
-data-dir <dir>- 环境变量
PWIKIT_DATA_DIR pwikit可执行文件所在的目录
对于支持 -data-dir 的命令，必须指定与正在运行的服务器相同的目录，否则命令将作用于另一个实例。目录结构参见部署。
命令如何查找数据库
serve、createsite、site、admin、user、seed、import、migrate、backup create 和 backup restore 按以下顺序连接数据库：
-database <connection string>- 环境变量
DATABASE_URL pwikit.toml中的database- 以上均未指定时，使用数据目录中的内置 PostgreSQL
使用内置 PostgreSQL 时：
- 若同一数据目录的
pwikit serve正在运行，命令使用serve启动的 PostgreSQL。 - 若没有任何进程在运行，命令会自行启动内置 PostgreSQL，并在命令结束后将其停止。
- 若另一个 pwikit 命令正在使用它，命令会以
another pwikit command, process <pid>, is already running the bundled PostgreSQL in this directory报错退出。请等待该命令结束。出于同样的原因，此时pwikit serve也无法启动。 - 请使用拥有数据目录的账户执行命令；以系统服务方式运行时，即为服务所用的账户。在 Linux 上也可以使用 root，此时内置 PostgreSQL 以单独的账户运行（参见以 root 身份运行）。在 macOS 上，内置 PostgreSQL 不以 root 身份运行。
连接字符串的格式为 postgres://user:password@host:5432/dbname。backup list、backup verify、service、render 和 modules 不按上述方式查找数据库。
serve
pwikit serve [options]运行 Web 服务器。启动时，serve 依次：
- 创建数据目录，若不存在
pwikit.toml则写入一份全部注释掉的模板； - 若未配置会话密钥，则创建
secrets/session-key； - 若未配置数据库，则启动内置 PostgreSQL；
- 拒绝低于 14 的 PostgreSQL 版本；
- 应用待执行的结构迁移（指定
-no-migrate时跳过）； - 开始监听。
按 Ctrl+C 或通过系统服务停止运行，内置 PostgreSQL 会随之停止。
若未配置数据库且 5432 端口已被占用，serve 会提示本机可能运行着您自行安装的 PostgreSQL，并说明如何通过 -database 使用它。pwikit 不会主动连接该端口，内置 PostgreSQL 使用自己的端口。
每项设置按命令行、环境变量、pwikit.toml、默认值的顺序取值。参见配置。
| 参数 | 默认值 | 环境变量 | pwikit.toml | 说明 |
|---|---|---|---|---|
-data-dir | 可执行文件所在目录 | PWIKIT_DATA_DIR | 数据目录 | |
-database | 内置 PostgreSQL | DATABASE_URL | database | PostgreSQL 连接字符串 |
-listen | 127.0.0.1:8080；启用 HTTPS 时为 :80 | server.listen | 纯 HTTP 的监听地址。启用 HTTPS 时，该端口将请求重定向到 HTTPS | |
-tls | off；有站点绑定公网域名时为 auto（见下文） | PWIKIT_TLS | tls.mode | off：纯 HTTP，用于反向代理之后。file：使用您提供的证书启用 HTTPS。auto：通过 ACME 自动获取证书启用 HTTPS |
-tls-listen | :443 | PWIKIT_TLS_LISTEN | tls.listen | HTTPS 的监听地址 |
-tls-cert | PWIKIT_TLS_CERT | tls.cert | PEM 格式的证书链，用于 -tls=file | |
-tls-key | PWIKIT_TLS_KEY | tls.key | PEM 格式的私钥，用于 -tls=file | |
-acme-email | PWIKIT_ACME_EMAIL | tls.acme_email | 向证书颁发机构登记的联系地址 | |
-acme-directory | Let's Encrypt | PWIKIT_ACME_DIRECTORY | tls.acme_directory | ACME 目录 URL |
-trusted-proxies | 无 | server.trusted_proxies | 受信任的反向代理地址或 CIDR 网段，以逗号分隔；只采信这些地址发来的 X-Forwarded-* 请求头 | |
-upload-limit | 0（不限） | MEDIA_UPLOAD_LIMIT | server.upload_limit | 页面附件的总大小上限，如 4GB |
-storage-limit | 0（不限） | ABSOLUTE_MEDIA_UPLOAD_LIMIT | server.storage_limit | 磁盘上所有上传文件的总大小上限，包括已删除的文件 |
-secret-key | secrets/session-key 的内容 | SECRET_KEY | 用于签名登录 Cookie 和邮件中链接的密钥 | |
-no-migrate | 关闭 | 启动时不应用待执行的结构迁移 | ||
-log-file | 标准错误输出 | 追加写入日志的文件。达到 10 MB 时轮转，保留 5 份旧文件 | ||
-static-dir | 内置资源 | 改为从该目录提供网页界面资源文件（通过 /-/static/），而不使用内置的副本。仅在修改网页界面时需要 | ||
-sidecar | PWIKIT_FTML_SIDECAR | 开发用参数：独立渲染程序的路径。请留空 | ||
-dev | 关闭 | 开发模式，见下文 | ||
-update-auto | true | PWIKIT_UPDATE_AUTO | update.auto | 以系统服务方式运行时自动安装新版本 |
-update-public-banner | true | PWIKIT_UPDATE_PUBLIC_BANNER | update.public_banner | 向所有访问者显示自动更新横幅 |
-update-check | true | PWIKIT_UPDATE_CHECK | update.check | 检查新版本 |
-update-window | 03:00-05:00 | PWIKIT_UPDATE_WINDOW | update.window | 自动安装新版本的时段，按 -update-time-zone 计算 |
-update-time-zone | 空 | PWIKIT_UPDATE_TIME_ZONE | update.time_zone | 更新时段所用的时区，如 Asia/Shanghai；留空时使用服务器的时区 |
-update-min-age | 0s | PWIKIT_UPDATE_MIN_AGE | update.min_age | 版本发布满这么久才会自动安装 |
-update-mirror | PWIKIT_UPDATE_MIRROR | update.mirror | GitHub 无法访问时使用的镜像。见更新与回档 |
大小的写法为数字加可选单位：B、KB、MB、GB 或 TB（1 KB = 1024 字节）。
自动 HTTPS。 若 -tls、-listen 和 -trusted-proxies 均未设置（包括命令行、环境变量和 pwikit.toml），serve 会检查数据库中的站点：只要有站点绑定了公网域名，即切换为 -tls=auto 并监听 :80 和 :443；否则在 127.0.0.1:8080 上提供纯 HTTP。从 HTTP 切换到 HTTPS 需要重启；已在提供 HTTPS 的实例绑定新域名则无需重启。参见部署。
开发模式
pwikit serve -dev 只在本机提供纯 HTTP，不受站点和设置影响。可用于在本地查看线上站点的副本。
- 监听
127.0.0.1:8080。-listen 9000或-listen :9000可在同一地址上改用其他端口；也接受-listen localhost:9000等回环地址。 - 可被其他机器访问的地址（如
-listen 0.0.0.0:9000）会被拒绝并报错。 -dev与-tls=auto或-tls=file同时指定会被拒绝并报错。- 忽略环境变量和
pwikit.toml中的 TLS、监听地址和受信任代理设置；数据库、会话密钥和上传上限照常读取。
示例
# 使用内置 PostgreSQL，有站点绑定公网域名后自动启用 HTTPS
pwikit serve
# 在 http://127.0.0.1:9000 上查看站点的本地副本
pwikit serve -dev -listen 9000
# 位于同一台机器上的反向代理之后
pwikit serve -tls=off -listen 127.0.0.1:8080 -trusted-proxies 127.0.0.1
# 使用自己的证书
pwikit serve -tls=file -tls-cert /etc/pwikit/fullchain.pem -tls-key /etc/pwikit/privkey.pem
# 使用自己的 PostgreSQL
pwikit serve -database "postgres://pwikit:secret@db.internal:5432/pwikit"createsite
pwikit createsite -slug <slug> -domain <domain> -title <title> -headline <subtitle> [options]创建站点。-slug、-domain、-title 和 -headline 为必填项。命令先像 serve 一样创建数据目录中的 files/、archive/、secrets/，并在不存在 pwikit.toml 时写入模板，因此新实例执行完这条命令就能看到完整的目录结构。创建站点之前，命令会像 migrate up 一样应用数据库缺失的迁移，并逐项输出 applied <name> 或 adopted <name>，因此也可在新建的空数据库上使用。
| 参数 | 默认值 | 说明 |
|---|---|---|
-slug | 站点标识名：字母、数字、- 和 _ | |
-domain | 页面所用的域名，不含协议和路径。可以带端口，如 localhost:8080 | |
-media-domain | 与 -domain 相同 | 上传文件所用的域名 |
-title | 站点标题 | |
-headline | 站点副标题 | |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
命令输出 created site <slug> (<id>) on <domain>。若域名为公网域名，还会提示 pwikit serve 启动（或已在运行时重启）后即可通过 https://<domain> 访问。
pwikit createsite -slug main -domain wiki.example.org -media-domain files.example.org \
-title "Example Wiki" -headline "A wiki about examples"site list
pwikit site list [-database <url>] [-data-dir <dir>]输出每个站点的标识名、域名和文件域名。
SLUG DOMAIN MEDIA DOMAIN
main wiki.example.org files.example.orgsite rebind
pwikit site rebind -slug <slug> -domain <domain> [-media-domain <domain>] [options]将站点改绑到其他域名。适用于原域名已无法访问的情况，例如域名变更后无人能够进入管理后台。更改对正在运行的服务器立即生效；若从 HTTP 改绑到公网域名并启用 HTTPS，则需要重启。
| 参数 | 默认值 | 说明 |
|---|---|---|
-slug | 要更改的站点 | |
-domain | 页面的新域名 | |
-media-domain | 与 -domain 相同 | 上传文件的新域名。若站点使用单独的文件域名，请一并指定 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
pwikit site rebind -slug main -domain wiki.example.net -media-domain files.example.netmain: wiki.example.org -> wiki.example.net
main: files.example.org -> files.example.net (media)
https://wiki.example.net answers once pwikit serve starts, or restarts if it is already runningadmin
pwikit admin <create|grant|revoke> -name <name> [options]拥有全部权限的账号即超级管理员：不受身份组限制，拥有所有权限，并可进入管理后台。
| 参数 | 默认值 | 说明 |
|---|---|---|
-name | 账号名称。允许包含空格和非拉丁文字 | |
-password-stdin | 关闭 | 仅用于 create：从标准输入读取密码，不进行交互式询问 |
-yes | 关闭 | 仅用于 create：不经确认直接创建新账号 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
账号名称
-name 是他人看到的名称。连续的空白会合并为一个空格，且名称必须：
- 不超过 50 个字符；
- 至少包含一个字母或数字；
- 不以组合附加符号开头，不包含不可见字符；
- 不采用保留的
wkt-uid-<number>形式。
账号的用户名由此生成：转为小写，并将每一段非字母、非数字的字符替换为一个 -。例如 -name "Site Admin" 生成的用户名为 site-admin。命令输出用户名和账号编号，如 site-admin (#1)。
admin create
将账号设为超级管理员并设置密码。
- 导入的账号。 若存在用户名或 Wikidot 用户名与之相符、且尚未设置密码的账号，
create会接管该账号：设置密码、激活账号并设为超级管理员，其导入的页面和帖子仍归属该账号。命令输出took over <username> (#<id>), imported as "<Wikidot name>"。请先导入 Wikidot 站点，参见从 Wikidot 导入。 - 已设置密码的现有账号。 命令终止，并提示改用
pwikit admin grant。 - 账号不存在。 命令说明将创建一个不含任何内容的新账号，并询问
Create a new account? [y/N]。输入y以外的任何内容均会取消。指定-yes可跳过此询问。
密码以不回显的方式输入。指定 -password-stdin 或标准输入不是终端时，使用标准输入的第一行作为密码。需要确认时，确认的回答同样从标准输入读取，因此在脚本中创建新账号应同时指定 -yes。
密码至少 8 个字符，不能全为数字，不能是常见密码，也不能与账号名称过于相似。
pwikit admin create -name "Site Admin"printf '%s\n' "$ADMIN_PASSWORD" | pwikit admin create -name "Site Admin" -yes -password-stdinadmin grant
pwikit admin grant -name <name>将现有账号设为超级管理员。可按用户名或 Wikidot 用户名查找账号。若该账号已是超级管理员，则不做更改。
admin revoke
pwikit admin revoke -name <name>收回账号的超级管理员权限，账号本身保留。若这是最后一个超级管理员，命令会警告：在执行 pwikit admin grant 之前，没有人能够进入管理后台。
user merge
pwikit user merge -from <account> -into <account> [options]把一个账号在实例所有站点上的全部记录移到另一个账号，然后删除前者。用于合并同一个人的两个账号，例如导入 Wikidot 站点之前就已注册的账号，与导入时另外建立的 wd: 账号。
| 参数 | 默认值 | 说明 |
|---|---|---|
-from | 被合并掉的账号 | |
-into | 保留的账号 | |
-yes | 关闭 | 不经确认直接合并 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
两个参数都可以用三种写法指定账号：
名字：按用户名查找，名字按账号名称的规则转为用户名。wd:名字：按该账号在 Wikidot 上的用户名查找，已认领和未认领的账号都可以。#编号：按账号编号查找。
合并时：
- 所有指向
-from的记录改为指向-into，包括页面作者、版本、评分、收藏、论坛主题与帖子、点赞、身份组、处置、私信、通知与关注、用户检举与支持工单。 - 两个账号在同一处都有记录时，保留
-into的那一条。例如两者都给同一页面评过分，保留-into的评分；两者都持有同一身份组，只保留一份。 -into没有 Wikidot 用户名与编号时，接收-from的，此后再导入的站点会直接归入-into。显示名、头像与个人简介在-into中为空时同样接收。用户名、邮箱、密码与超级管理员权限一律保留-into的。-from被删除，仍以它登录的会话变为未登录。
以下情况命令会拒绝执行：两个参数指向同一个账号；-into 是尚未认领的 Wikidot 账号，这种账号无法登录，请反过来合并；两个账号分别来自两个不同的 Wikidot 账号。
未指定 -yes 时，命令说明将发生的事并询问 Merge? [y/N]，输入 y 以外的任何内容均会取消。合并无法撤销，请先执行 pwikit backup create。完成后，命令逐项输出移动的记录数与作为重复删除的记录数，最后输出 merged <from> into <into>。
pwikit user merge -from wd:Kakushi -into kakushiseed
pwikit seed [-site <slug>] [options]写入新站点的初始页面：main、nav:top、nav:top-impl、nav:side、search:site、forum:start、forum:category、forum:thread、forum:new-thread 和 forum:recent-posts。已存在的页面不会被改动，因此可以重复执行。命令逐个输出写入的页面，最后输出 <n> of 10 pages written, the rest were already there。
| 参数 | 默认值 | 说明 |
|---|---|---|
-site | 唯一的站点 | 写入的站点。数据库中有多个站点时必须指定 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
pwikit seedimport
pwikit import [directory] [options]从已解压的 wikitCLI 备份导入 Wikidot 站点。目录是站点目录，或与 _users/ 放在一起、存放多个站点目录的上层目录。指定站点目录时，也会读取与它同级的 _users/。不指定目录时读取数据目录中的 archive/。参数写在目录之前或之后均可。参见从 Wikidot 导入。
| 参数 | 默认值 | 说明 |
|---|---|---|
-site | 唯一的站点 | 写入的站点。数据库中有多个站点时必须指定 |
-from | 备份中唯一的站点 | 备份中的站点。备份包含多个站点时必须指定 |
-no-tags | 关闭 | 不导入标签 |
-no-votes | 关闭 | 不导入评分 |
-no-files | 关闭 | 不导入附件 |
-no-accounts | 关闭 | 不建立任何账号，即使备份中带有账号。导入的内容没有作者 |
-own-users | 关闭 | 只从站点目录内的 _users/ 读取账号，不读取与站点目录同级的共用 _users/ |
-used-users | 关闭 | 只为本次导入的页面版本、评分、附件与论坛中出现过的用户建立账号 |
-user-backfill | 关闭 | 对已存在的页面，按备份补上缺失的作者与评分，见从 Wikidot 导入 |
-update | 关闭 | 用更新的备份更新已存在的页面，并补上缺少的评分、附件与论坛帖子，执行前需确认，见从 Wikidot 导入 |
-yes | 关闭 | 与 -update 一起使用时，不经确认直接执行 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录；未指定目录时从其中的 archive/ 读取备份，附件复制到其中的 files/ |
pwikit import
pwikit import /srv/wikidot-backup -from my-wikireindex
pwikit reindex [-site <slug>] [options]
pwikit reindex -all [options]读取站点的每个页面（包含隐藏页面），重新写入搜索索引。页面在搜索结果中缺失，或导入页面之后，可执行此命令。没有源代码的页面会被跳过。每个站点输出一行 <slug>: <n> pages indexed。
| 参数 | 默认值 | 说明 |
|---|---|---|
-site | 唯一的站点 | 要处理的站点。数据库中有多个站点时必须指定 |
-all | 关闭 | 处理数据库中的每个站点，不能与 -site 同时使用 |
-database | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 可执行文件所在目录 | 数据目录 |
-sidecar | PWIKIT_FTML_SIDECAR 的值 | 开发选项：独立渲染程序的路径 |
pwikit reindex
pwikit reindex -allbackup
pwikit backup <create|list|verify|restore> [options] [file]备份是一个 .pwbak 文件，包含数据库以及（未排除时的）上传文件。备份文件名可以写在参数之前或之后。备份的内容与用法参见运维。
| 参数 | 适用于 | 默认值 | 说明 |
|---|---|---|---|
-output | create | backups/pwikit-<UTC time>.pwbak | 写入的文件 |
-no-files | create、restore | 关闭 | create：不包含上传文件。restore：不改动 files/ |
-site | create | 整个实例 | 单独导出一个站点 |
-keep-passwords | create | 关闭 | 在单站导出中保留账号密码 |
-dir | list | backups/ | 要列出的目录 |
-force | restore | 关闭 | 替换已有站点、账号或页面的数据库 |
-no-safety-backup | restore | 关闭 | 跳过 restore 事先对当前状态进行的备份 |
-database | create、restore | 参见命令如何查找数据库 | PostgreSQL 连接字符串 |
-data-dir | 全部 | 可执行文件所在目录 | 数据目录 |
backup create
pwikit backup create [-output <file>] [-no-files] [-site <slug> [-keep-passwords]]写入备份。可在 pwikit serve 运行期间执行。进度输出到标准错误；完成后输出文件路径和摘要，如 63 tables, 12840 rows, 312 files, 85.2 MB。未指定 -output 时，文件写入 backups/，名称为 pwikit-20260911-030000.pwbak；单站导出为 pwikit-<slug>-20260911-030000.pwbak（时间为 UTC）。
pwikit backup create
pwikit backup create -output /mnt/backup/wiki.pwbak
pwikit backup create -site mainbackup list
pwikit backup list [-dir <dir>]列出 backups/ 中的 .pwbak 文件，最新的在前。无需数据库。
FILE MADE PWIKIT POSTGRES ROWS FILES SIZE
pwikit-20260911-030000.pwbak 2026-09-11 03:00 0a1b2c3d4e5f 18.6 12840 312 85.2 MBMADE 为 UTC 时间。使用 -no-files 创建的备份，FILES 列显示 no。无法读取的文件显示为 UNREADABLE，原因输出在表格之后。
backup verify
pwikit backup verify <file>完整读取备份并与其清单逐项核对。无需数据库。命令输出备份的创建时间、创建它的 pwikit 版本、PostgreSQL 版本、所含内容、提示信息和发现的问题；没有问题时输出 sound。备份不完好时，命令以错误状态退出。
backups/pwikit-20260911-030000.pwbak
made 2026-09-11T03:00:00Z by pwikit 0a1b2c3d4e5f
postgres 18.6
holds 63 tables, 12840 rows, 312 files
soundbackup restore
pwikit backup restore <file> [-force] [-no-safety-backup] [-no-files] [-database <url>]用备份的内容替换数据库；备份包含上传文件且未指定 -no-files 时，也替换上传文件。请先停止 pwikit serve。在进行任何更改之前，命令会将当前状态备份到 backups/before-restore-pwikit-<UTC time>.pwbak；指定 -no-safety-backup 或数据库中尚无数据时跳过这一步。参见恢复备份。
pwikit backup restore backups/pwikit-20260911-030000.pwbak -forceservice
pwikit service <install|uninstall|start|stop|status|print> [options] [-- serve options]将 pwikit 注册到操作系统，使 pwikit serve 随开机启动：Linux 上为 systemd 单元，macOS 上为 launchd 任务，Windows 上为 Windows 服务。安装方法参见部署，日常管理参见运维。
| 子命令 | 说明 |
|---|---|
install | 注册服务，立即启动并随开机启动 |
uninstall | 停止服务并将其移除 |
start | 启动已安装的服务 |
stop | 停止已安装的服务 |
status | 显示服务是否正在运行 |
print | 显示 install 将注册的内容，但不实际注册 |
| 参数 | 默认值 | 说明 |
|---|---|---|
-name | pwikit | 服务注册的名称：字母、数字、.、- 和 _ |
-user | 执行 sudo 的账户 | 仅用于 Linux 和 macOS 上的 install 与 print：服务运行所用的账户。在 Linux 上由 root 安装且未指定时，服务以 root 身份运行；在 macOS 上不能是 root |
-data-dir | 可执行文件所在目录 | 仅用于 install 与 print：服务使用的数据目录 |
-no-path | 关闭 | 仅用于 install 与 uninstall：不改动 pwikit 命令 |
-- 之后的所有内容会传给 pwikit serve，并在安装时进行检查。install 还会在防火墙中放行 pwikit：Windows 上为该程序添加入站规则；macOS 上，对于通过 sudo 安装的服务，在应用程序防火墙开启时放行；Linux 上，在 firewalld 或 ufw 运行时开放所需端口。uninstall 会撤销 install 所做的更改，并且只关闭它自己开放的端口。
| 平台 | install / uninstall / start / stop | status |
|---|---|---|
| Linux | 需要 sudo | 任意账户 |
| macOS | 使用 sudo 安装的服务随开机启动；不使用 sudo 安装的服务在登录时启动。之后的所有命令请保持相同的选择 | 与安装时相同 |
| Windows | 需要通过以管理员身份运行打开的终端 | 任意账户 |
install 默认还会执行 pwikit path install，使 pwikit 可以在任意目录直接输入；uninstall 默认一并撤销。这一步未能完成时只输出警告，服务照常安装。
install 还会注册检查与安装新版本的计划任务，uninstall 一并移除。见更新与回档。
install 拒绝在 go run 下执行；请先构建 pwikit，再安装构建出的可执行文件。
sudo ./pwikit service install
sudo ./pwikit service install -- -tls=auto -acme-email admin@example.org
./pwikit service printpath
pwikit path <install|uninstall|status> [options]让 pwikit 可以在任意目录直接输入。执行这条命令时，请以 ./pwikit（Windows 为 .\pwikit.exe）运行。说明与搬迁实例时的用法见部署。
| 子命令 | 说明 |
|---|---|
install | Linux 与 macOS 上建立指向本程序的 pwikit 链接；Windows 上将本程序所在目录加入当前用户的 Path |
uninstall | 撤销 install，只移除指向本程序或已失效的链接 |
status | 显示 pwikit 命令指向何处、是否失效、所在目录是否在 PATH 中 |
| 参数 | 默认值 | 说明 |
|---|---|---|
-dir | /usr/local/bin，无法写入时为 ~/.local/bin | 仅用于 Linux 与 macOS：放置链接的目录 |
-force | 关闭 | 替换指向另一个 pwikit 的链接，或同名的普通文件 |
指向已不存在位置的旧链接会被直接替换，因此搬迁实例后在新位置再次执行 install 即可。Windows 上不支持 -dir，完成后请重新打开终端。
sudo ./pwikit path install
./pwikit path install -dir ~/bin
pwikit path statusupdate
pwikit update [check|status|rollback|unpin|postpone|skip|mirror] [options] [-- serve options]安装新版本、回到上一个版本，或管理自动更新。完整说明见更新与回档。
| 子命令 | 说明 |
|---|---|
| 不写子命令 | 安装最新版本 |
check | 查询最新版本，不做任何更改 |
status | 显示最近一次检查、更新计划、上一次更新的结果和回档点 |
rollback | 回到更新前的版本；回档点包含数据库时一并放回数据库 |
unpin | 解除 -to 或 rollback 造成的版本固定 |
postpone | 取消当前的更新计划，24 小时内不自动更新 |
skip | 取消当前的更新计划，不再自动安装该版本 |
mirror [地址] | 不带地址时显示 pwikit.toml 中的镜像；带地址时写入 [update] mirror，文件中的其他内容保持不变；地址为空字符串时清除 |
| 参数 | 默认值 | 说明 |
|---|---|---|
-to | 最新版本 | 要安装的版本。比当前版本旧时，安装后固定在该版本 |
-service | pwikit | 已安装服务的名称 |
-data-dir | 可执行文件所在目录 | 数据目录 |
-mirror | [update] mirror 的值 | GitHub 无法访问时使用的镜像 |
-yes | 关闭 | rollback：不询问确认 |
-- 之后的参数与安装服务时相同，例如 -database，用于找到同一个数据库和设置。
以系统服务方式运行的实例，安装与回档需要在 Linux 与 macOS 上使用 sudo，在 Windows 上使用以管理员身份运行的终端。未以系统服务方式运行的实例，请先停止 pwikit serve。
sudo pwikit update
sudo pwikit update -to v1.0.1
pwikit update check
pwikit update status
sudo pwikit update rollbackmigrate
pwikit migrate <status|up> [-database <url>] [-data-dir <dir>]migrate status
列出每个结构迁移及其状态，不做任何更改。
STATUS MIGRATION
applied 0001_baseline.sql
applied 0002_admin_log_and_addresses.sql
pending 0003_site_columns.sql| 状态 | 含义 |
|---|---|
applied | 数据库已应用此迁移 |
pending | 数据库缺少此迁移；pwikit serve、pwikit createsite 或 pwikit migrate up 会应用它 |
existing | 数据库由较早的 ProjectWikit 版本创建，已具备此结构；此迁移将记为已应用，不会实际执行 |
newer | 较新版本的 pwikit 应用的迁移，本 pwikit 不认识，但声明为兼容旧版本。本 pwikit 可以继续运行 |
newer-breaking | 较新版本的 pwikit 应用的迁移，声明为不兼容旧版本。本 pwikit 拒绝在该数据库上启动 |
migrate up
应用缺失的迁移，每应用一项输出 applied <name>。状态为 existing 的迁移只记为已应用而不实际执行，并输出 adopted <name>。没有缺失的迁移时，输出 already up to date。除非指定 -no-migrate，pwikit serve 启动时也会执行相同的操作。
render
pwikit render [options] < page.txt
pwikit render -file page.txt [options]从标准输入或文件读取维基语法，渲染后输出结果。可用于在不打开浏览器的情况下检查一段维基语法的渲染效果。未指定 -dsn 时不使用数据库：链接不会被解析，包含（include）也找不到任何页面。此命令只读取 -dsn，不读取 DATABASE_URL、pwikit.toml，也不使用内置 PostgreSQL。
| 参数 | 默认值 | 说明 |
|---|---|---|
-file | 标准输入 | 要读取的文件 |
-mode | article | article、message、inline、system 或 system-with-modules |
-output | html | html；text；backlinks，输出被包含和被链接的页面；code，输出 [[code]] 和 [[html]] 块 |
-dsn | PostgreSQL 连接字符串 | |
-site | 唯一的站点 | 站点标识名；使用 -dsn 且数据库中有多个站点时必须指定 |
-page | page | 渲染时所用的页面名称 |
-category | _default | 该页面的分类 |
-domain | example.org | 站点域名 |
-modules | real | real 实际渲染模块；stub 改为输出每个模块的名称和参数 |
-trace | 将渲染器发出的请求写入此文件，- 表示标准错误输出 | |
-data-dir | 可执行文件所在目录 | 数据目录，用于读取身份组图标 |
-sidecar | PWIKIT_FTML_SIDECAR 的值 | 开发用参数：独立渲染程序的路径 |
echo "**bold** [[[main]]]" | pwikit render -output textmodules
pwikit modules列出 pwikit 可识别的所有 [[module]] 名称。
| 列 | 含义 |
|---|---|
MODULE | 模块名称 |
BODY | 为 true 时，模块接受直到 [[/module]] 为止的内容 |
STATUS | ported：可用。pending：可识别，但本版本尚不可用。removed：已不再提供 |
模块的用法参见模块。
version
pwikit version显示当前可执行文件的版本，不连接网络。报告问题时请附上这段输出。
pwikit v1.0.0
commit 1a2b3c4d5e6f
committed 2026-09-13T05:58:17Z
platform linux/amd64
postgresql 18.6.0, bundled
go go1.26.4| 行 | 含义 |
|---|---|
pwikit | 版本号。自行构建且未指定版本号时，显示提交编号 |
commit | 构建所用的提交；构建时有未提交的修改则带 -modified |
committed | 该提交的时间（UTC） |
platform | 操作系统与 CPU 架构 |
postgresql | 内置 PostgreSQL 的版本；不含内置 PostgreSQL 的构建显示 not bundled |
go | 构建所用的 Go 版本 |