Skip to content

命令行 ​

ProjectWikit 在浏览器之外的所有操作都通过 pwikit 可执行文件的子命令完成:

sh
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将站点改绑到其他域名
site delete删除站点
admin create创建首个管理员,或接管导入的账号
admin grant授予现有账号全部权限
admin revoke收回账号的全部权限
user merge将两个账号合并为一个
user prune删除没有被任何站点用到的导入账号
seed写入初始页面
import从 wikitCLI 备份导入 Wikidot 站点
reindex将站点的每个页面重新写入搜索索引,并重建反向链接
mirror管理其他 Wikidot 站点页面的只读镜像
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 按以下顺序确定数据目录:

  1. -data-dir <dir>
  2. 环境变量 PWIKIT_DATA_DIR
  3. pwikit 可执行文件所在的目录

对于支持 -data-dir 的命令,必须指定与正在运行的服务器相同的目录,否则命令将作用于另一个实例。目录结构参见部署。

命令如何查找数据库 ​

serve、createsite、site、admin、user、seed、import、migrate、backup create 和 backup restore 按以下顺序连接数据库:

  1. -database <connection string>
  2. 环境变量 DATABASE_URL
  3. pwikit.toml 中的 database
  4. 以上均未指定时,使用数据目录中的内置 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 ​

sh
pwikit serve [options]

运行 Web 服务器。启动时,serve 依次:

  1. 创建数据目录,若不存在 pwikit.toml 则写入一份全部注释掉的模板;
  2. 若未配置会话密钥,则创建 secrets/session-key;
  3. 若未配置数据库,则启动内置 PostgreSQL;
  4. 拒绝低于 14 的 PostgreSQL 版本;
  5. 应用待执行的结构迁移(指定 -no-migrate 时跳过);
  6. 开始监听。

按 Ctrl+C 或通过系统服务停止运行,内置 PostgreSQL 会随之停止。

若未配置数据库且 5432 端口已被占用,serve 会提示本机可能运行着您自行安装的 PostgreSQL,并说明如何通过 -database 使用它。pwikit 不会主动连接该端口,内置 PostgreSQL 使用自己的端口。

每项设置按命令行、环境变量、pwikit.toml、默认值的顺序取值。参见配置。

参数默认值环境变量pwikit.toml说明
-data-dir可执行文件所在目录PWIKIT_DATA_DIR数据目录
-database内置 PostgreSQLDATABASE_URLdatabasePostgreSQL 连接字符串
-listen127.0.0.1:8080;启用 HTTPS 时为 :80server.listen纯 HTTP 的监听地址。启用 HTTPS 时,该端口将请求重定向到 HTTPS
-tlsoff;有站点绑定公网域名时为 auto(见下文)PWIKIT_TLStls.modeoff:纯 HTTP,用于反向代理之后。file:使用您提供的证书启用 HTTPS。auto:通过 ACME 自动获取证书启用 HTTPS
-tls-listen:443PWIKIT_TLS_LISTENtls.listenHTTPS 的监听地址
-tls-certPWIKIT_TLS_CERTtls.certPEM 格式的证书链,用于 -tls=file
-tls-keyPWIKIT_TLS_KEYtls.keyPEM 格式的私钥,用于 -tls=file
-acme-emailPWIKIT_ACME_EMAILtls.acme_email向证书颁发机构登记的联系地址
-acme-directoryLet's EncryptPWIKIT_ACME_DIRECTORYtls.acme_directoryACME 目录 URL
-trusted-proxies无server.trusted_proxies受信任的反向代理地址或 CIDR 网段,以逗号分隔;只采信这些地址发来的 X-Forwarded-* 请求头
-upload-limit0(不限)MEDIA_UPLOAD_LIMITserver.upload_limit页面附件的总大小上限,如 4GB
-storage-limit0(不限)ABSOLUTE_MEDIA_UPLOAD_LIMITserver.storage_limit磁盘上所有上传文件的总大小上限,包括已删除的文件
-secret-keysecrets/session-key 的内容SECRET_KEY用于签名登录 Cookie 和邮件中链接的密钥
-no-migrate关闭启动时不应用待执行的结构迁移
-log-file标准错误输出追加写入日志的文件。达到 10 MB 时轮转,保留 5 份旧文件
-static-dir内置资源改为从该目录提供网页界面资源文件(通过 /-/static/),而不使用内置的副本。仅在修改网页界面时需要
-sidecarPWIKIT_FTML_SIDECAR开发用参数:独立渲染程序的路径。请留空
-dev关闭开发模式,见下文
-update-autotruePWIKIT_UPDATE_AUTOupdate.auto以系统服务方式运行时自动安装新版本
-update-public-bannertruePWIKIT_UPDATE_PUBLIC_BANNERupdate.public_banner向所有访问者显示自动更新横幅
-update-checktruePWIKIT_UPDATE_CHECKupdate.check检查新版本
-update-window03:00-05:00PWIKIT_UPDATE_WINDOWupdate.window自动安装新版本的时段,按 -update-time-zone 计算
-update-time-zone空PWIKIT_UPDATE_TIME_ZONEupdate.time_zone更新时段所用的时区,如 Asia/Shanghai;留空时使用服务器的时区
-update-min-age0sPWIKIT_UPDATE_MIN_AGEupdate.min_age版本发布满这么久才会自动安装
-update-mirrorPWIKIT_UPDATE_MIRRORupdate.mirrorGitHub 无法访问时使用的镜像。见更新与回档

大小的写法为数字加可选单位: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、监听地址和受信任代理设置;数据库、会话密钥和上传上限照常读取。

示例 ​

sh
# 使用内置 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 ​

sh
pwikit createsite -slug <slug> -domain <domain> -title <title> -headline <subtitle> [options]

创建站点。-slug、-domain、-title 和 -headline 为必填项。命令先像 serve 一样创建数据目录中的 files/、archive/、secrets/,并在不存在 pwikit.toml 时写入模板;创建站点之前,会像 migrate up 一样应用数据库缺失的迁移。

参数默认值说明
-slug站点标识名:字母、数字、- 和 _
-domain页面所用的域名,不含协议和路径。可以带端口,如 localhost:8080
-media-domain与 -domain 相同上传文件所用的域名
-title站点标题
-headline站点副标题
-languageen站点语言,可选 en 与 zh-hans,决定预置身份组的名称。之后可在管理后台的 站点设置 中更改
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录

命令输出 created site <slug> (<id>) on <domain>。指定了没有译文的语言时,命令列出可用的语言并退出,不创建站点。

sh
pwikit createsite -slug main -domain wiki.example.org -media-domain files.example.org \
  -title "Example Wiki" -headline "A wiki about examples"

site list ​

sh
pwikit site list [-database <url>] [-data-dir <dir>]

输出每个站点的标识名、域名和文件域名。

text
SLUG  DOMAIN            MEDIA DOMAIN
main  wiki.example.org  files.example.org

site rebind ​

sh
pwikit site rebind -slug <slug> -domain <domain> [-media-domain <domain>] [options]

将站点改绑到其他域名。适用于原域名已无法访问的情况,例如域名变更后无人能够进入管理后台。更改对正在运行的服务器立即生效;若从 HTTP 改绑到公网域名并启用 HTTPS,则需要重启。

参数默认值说明
-slug要更改的站点
-domain页面的新域名
-media-domain与 -domain 相同上传文件的新域名。若站点使用单独的文件域名,请一并指定
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录
sh
pwikit site rebind -slug main -domain wiki.example.net -media-domain files.example.net
text
main: 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 running

site delete ​

sh
pwikit site delete -slug <slug> [-database <url>] [-data-dir <dir>]

删除站点及其全部页面、论坛、文件、身份组与设置。账号属于整个实例,不会被删除。

删除前会先询问是否备份整个实例,再要求输入站点的标识名确认。没有备份时还须输入 delete forever,最后再确认一次。删除后请重启正在运行的 pwikit serve。

admin ​

sh
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 个字符,不能全为数字,不能是常见密码,也不能与账号名称过于相似。

sh
pwikit admin create -name "Site Admin"
sh
printf '%s\n' "$ADMIN_PASSWORD" | pwikit admin create -name "Site Admin" -yes -password-stdin

admin grant ​

sh
pwikit admin grant -name <name>

将现有账号设为超级管理员。可按用户名或 Wikidot 用户名查找账号。若该账号已是超级管理员,则不做更改。

admin revoke ​

sh
pwikit admin revoke -name <name>

收回账号的超级管理员权限,账号本身保留。若这是最后一个超级管理员,命令会警告:在执行 pwikit admin grant 之前,没有人能够进入管理后台。

user merge ​

sh
pwikit user merge -from <account> -into <account> [options]

把一个账号在实例所有站点上的全部记录移到另一个账号,然后删除前者。用于合并同一个人的两个账号,例如导入 Wikidot 站点之前就已注册的账号,与导入时另外建立的 wd: 账号。

参数默认值说明
-from被合并掉的账号
-into保留的账号
-yes关闭不经确认直接合并
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录

两个参数都可以用三种写法指定账号:

  • 名字:按用户名查找,名字按账号名称的规则转为用户名。
  • wd:名字:按该账号在 Wikidot 上的用户名查找,已认领和未认领的账号都可以。
  • #编号:按账号编号查找。

在终端中使用 #编号 时须加引号,否则 # 及其后的内容会被当作注释忽略:

sh
pwikit user merge -from '#3404' -into '#121'

合并时:

  • 所有指向 -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>。

sh
pwikit user merge -from wd:Kakushi -into kakushi

user prune ​

sh
pwikit user prune [-apply] [options]

列出没有被任何站点用到的导入账号,指定 -apply 时将其删除。用于清理导入时一并带进来的其他站点的账号,例如备份的 _users 目录中含有其他站点的用户。

参数默认值说明
-apply关闭删除列出的账号;不指定时只列出,不删除
-yes关闭不经确认直接删除
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录

只处理尚未认领的 Wikidot 账号。在本实例注册或已认领的账号一律保留。导入账号只要在任何站点上留有以下任意一项记录就会保留:页面作者、版本、文件、评分、收藏、论坛主题与帖子、点赞、身份组、处置、私信、通知与关注、用户检举与支持工单、邀请链接、操作记录。页面或帖子中用 [[user]] 提到的账号同样保留。

命令先列出前 20 个账号与总数,再说明有多少账号因被页面或帖子提到而保留。删除在一个事务中完成,执行时会再次检查每个账号,期间新增了记录的账号不会被删除。

未指定 -yes 时,命令询问 Delete? [y/N],输入 y 以外的任何内容均会取消。删除无法撤销,请先执行 pwikit backup create。被删除的账号无法再认领;之后再导入提到它们的备份时,会重新建立这些账号。

sh
# 先查看会删除哪些账号
pwikit user prune
# 确认无误后删除
pwikit user prune -apply

seed ​

sh
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可执行文件所在目录数据目录
sh
pwikit seed

import ​

sh
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/
sh
pwikit import
pwikit import /srv/wikidot-backup -from my-wiki

reindex ​

sh
pwikit reindex [-site <slug>] [options]
pwikit reindex -all [options]

读取站点的每个页面(包含隐藏页面),重新写入搜索索引,并重新记录每个页面链接与引入的页面。页面在搜索结果或反向链接中缺失,或导入页面之后,可执行此命令。没有源代码的页面会被跳过。每个站点输出一行 <slug>: <n> pages indexed。

参数默认值说明
-site唯一的站点要处理的站点。数据库中有多个站点时必须指定
-all关闭处理数据库中的每个站点,不能与 -site 同时使用
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录
-sidecarPWIKIT_FTML_SIDECAR 的值开发选项:独立渲染程序的路径
sh
pwikit reindex
pwikit reindex -all

mirror ​

sh
pwikit mirror <scan|missing|list|refs|show|fetch|refetch|delete> [options] [:<站点>:<页面> ...]

管理其他 Wikidot 站点页面的只读镜像,参见外部页面镜像。未指定 -site 时处理数据库中的每个站点。

子命令说明
scan找出页面中的全部 [[include :站点:页面]],每个站点输出一行统计
missing列出既不在本实例中、也没有镜像的外部页面,以及引用它们的页面
list列出全部镜像、状态、抓取时间与引用数
refs列出引用所给镜像的页面
show输出所给镜像的源代码
fetch抓取全部缺失的页面,并跟进它们插入的页面
refetch重新抓取所给的镜像;加 -all 重新抓取全部镜像
delete删除所给的镜像
参数默认值说明
-site全部站点要处理的站点
-all关闭与 refetch 一起使用,重新抓取全部镜像
-per-site5对同一个 Wikidot 站点同时发出的请求数
-total20同时发出的请求总数
-database参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir可执行文件所在目录数据目录
sh
pwikit mirror scan
pwikit mirror fetch
pwikit mirror refetch :scp-wiki-cn:component:license-box

backup ​

sh
pwikit backup <create|list|verify|restore> [options] [file]

备份是一个 .pwbak 文件,包含数据库以及(未排除时的)上传文件。备份文件名可以写在参数之前或之后。备份的内容与用法参见运维。

参数适用于默认值说明
-outputcreatebackups/pwikit-<UTC time>.pwbak写入的文件
-no-filescreate、restore关闭create:不包含上传文件。restore:不改动 files/
-sitecreate整个实例单独导出一个站点
-keep-passwordscreate关闭在单站导出中保留账号密码
-dirlistbackups/要列出的目录
-forcerestore关闭替换已有站点、账号或页面的数据库
-no-safety-backuprestore关闭跳过 restore 事先对当前状态进行的备份
-databasecreate、restore参见命令如何查找数据库PostgreSQL 连接字符串
-data-dir全部可执行文件所在目录数据目录

backup create ​

sh
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)。

sh
pwikit backup create
pwikit backup create -output /mnt/backup/wiki.pwbak
pwikit backup create -site main

backup list ​

sh
pwikit backup list [-dir <dir>]

列出 backups/ 中的 .pwbak 文件,最新的在前。无需数据库。

text
FILE                           MADE              PWIKIT        POSTGRES  ROWS   FILES  SIZE
pwikit-20260911-030000.pwbak   2026-09-11 03:00  0a1b2c3d4e5f  18.6      12840  312    85.2 MB

MADE 为 UTC 时间。使用 -no-files 创建的备份,FILES 列显示 no。无法读取的文件显示为 UNREADABLE,原因输出在表格之后。

backup verify ​

sh
pwikit backup verify <file>

完整读取备份并与其清单逐项核对。无需数据库。命令输出备份的创建时间、创建它的 pwikit 版本、PostgreSQL 版本、所含内容、提示信息和发现的问题;没有问题时输出 sound。备份不完好时,命令以错误状态退出。

text
backups/pwikit-20260911-030000.pwbak
  made      2026-09-11T03:00:00Z by pwikit 0a1b2c3d4e5f
  postgres  18.6
  holds     63 tables, 12840 rows, 312 files
  sound

backup restore ​

sh
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 或数据库中尚无数据时跳过这一步。参见恢复备份。

sh
pwikit backup restore backups/pwikit-20260911-030000.pwbak -force

service ​

sh
pwikit service <install|uninstall|start|stop|restart|status|print> [options] [-- serve options]

将 pwikit 注册到操作系统,使 pwikit serve 随开机启动:Linux 上为 systemd 单元,macOS 上为 launchd 任务,Windows 上为 Windows 服务。安装方法参见部署,日常管理参见运维。

子命令说明
install注册服务,立即启动并随开机启动
uninstall停止服务并将其移除
start启动已安装的服务
stop停止已安装的服务
restart停止已安装的服务并重新启动
status显示服务是否正在运行
print显示 install 将注册的内容,但不实际注册
参数默认值说明
-namepwikit服务注册的名称:字母、数字、.、- 和 _
-user执行 sudo 的账户仅用于 Linux 和 macOS 上的 install 与 print:服务运行所用的账户。在 Linux 上由 root 直接安装且未指定时,服务以专用账户 pwikit 运行;在 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 / restartstatus
Linux需要 sudo任意账户
macOS使用 sudo 安装的服务随开机启动;不使用 sudo 安装的服务在登录时启动。之后的所有命令请保持相同的选择与安装时相同
Windows需要通过以管理员身份运行打开的终端任意账户

install 默认还会执行 pwikit path install,使 pwikit 可以在任意目录直接输入;uninstall 默认一并撤销。这一步未能完成时只输出警告,服务照常安装。

install 还会注册检查与安装新版本的计划任务,uninstall 一并移除。见更新与回档。

sh
sudo ./pwikit service install
sudo ./pwikit service install -- -tls=auto -acme-email admin@example.org
./pwikit service print

path ​

sh
pwikit path <install|uninstall|status> [options]

让 pwikit 可以在任意目录直接输入。执行这条命令时,请以 ./pwikit(Windows 为 .\pwikit.exe)运行。说明与搬迁实例时的用法见部署。

子命令说明
installLinux 与 macOS 上建立指向本程序的 pwikit 链接;Windows 上将本程序所在目录加入当前用户的 Path
uninstall撤销 install,只移除指向本程序或已失效的链接
status显示 pwikit 命令指向何处、是否失效、所在目录是否在 PATH 中
参数默认值说明
-dir/usr/local/bin,无法写入时为 ~/.local/bin仅用于 Linux 与 macOS:放置链接的目录
-force关闭替换指向另一个 pwikit 的链接,或同名的普通文件

指向已不存在位置的旧链接会被直接替换,因此搬迁实例后在新位置再次执行 install 即可。Windows 上不支持 -dir,完成后请重新打开终端。

sh
sudo ./pwikit path install
./pwikit path install -dir ~/bin
pwikit path status

update ​

sh
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最新版本要安装的版本。比当前版本旧时,安装后固定在该版本
-servicepwikit已安装服务的名称
-data-dir可执行文件所在目录数据目录
-mirror[update] mirror 的值GitHub 无法访问时使用的镜像
-yes关闭rollback:不询问确认

-- 之后的参数与安装服务时相同,例如 -database,用于找到同一个数据库和设置。

以系统服务方式运行的实例,安装与回档需要在 Linux 与 macOS 上使用 sudo,在 Windows 上使用以管理员身份运行的终端。未以系统服务方式运行的实例,请先停止 pwikit serve。

sh
sudo pwikit update
sudo pwikit update -to v1.0.1
pwikit update check
pwikit update status
sudo pwikit update rollback

migrate ​

sh
pwikit migrate <status|up> [-database <url>] [-data-dir <dir>]

migrate status ​

列出每个结构迁移及其状态,不做任何更改。

text
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 ​

sh
pwikit render [options] < page.txt
pwikit render -file page.txt [options]

从标准输入或文件读取维基语法,渲染后输出结果。可用于在不打开浏览器的情况下检查一段维基语法的渲染效果。未指定 -dsn 时不使用数据库:链接不会被解析,包含(include)也找不到任何页面。此命令只读取 -dsn,不读取 DATABASE_URL、pwikit.toml,也不使用内置 PostgreSQL。

参数默认值说明
-file标准输入要读取的文件
-modearticlearticle、message、inline、system 或 system-with-modules
-outputhtmlhtml;text;backlinks,输出被包含和被链接的页面;code,输出 [[code]] 和 [[html]] 块
-dsnPostgreSQL 连接字符串
-site唯一的站点站点标识名;使用 -dsn 且数据库中有多个站点时必须指定
-pagepage渲染时所用的页面名称
-category_default该页面的分类
-domainexample.org站点域名
-modulesrealreal 实际渲染模块;stub 改为输出每个模块的名称和参数
-trace将渲染器发出的请求写入此文件,- 表示标准错误输出
-data-dir可执行文件所在目录数据目录,用于读取身份组图标
-sidecarPWIKIT_FTML_SIDECAR 的值开发用参数:独立渲染程序的路径
sh
echo "**bold** [[[main]]]" | pwikit render -output text

modules ​

sh
pwikit modules

列出 pwikit 可识别的所有 [[module]] 名称。

列含义
MODULE模块名称
BODY为 true 时,模块接受直到 [[/module]] 为止的内容
STATUSported:可用。pending:可识别,但本版本尚不可用。removed:已不再提供

模块的用法参见模块。

version ​

sh
pwikit version

显示当前可执行文件的版本,不连接网络。报告问题时请附上这段输出。

text
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 版本