挂载外部程序
pwikit 可以将站点下的一个路径转发给同一台机器上的其他程序,例如将 /scpper/ 交给 scpper。读者访问的仍是同一个站点,登录状态由 pwikit 告知该程序。
配置
在 pwikit.toml 中为每个程序添加一段 [[mount]],然后重启 pwikit:
[[mount]]
path = "/scpper/"
upstream = "http://127.0.0.1:8100"
strip_prefix = true
secret_file = "mount-scpper.key"| 字段 | 说明 |
|---|---|
path | 转发的路径,以 / 开头和结尾,不可位于 /-/ 或 /pw-api/ 之下 |
upstream | 程序的地址 |
strip_prefix | 为 true 时去除 path 后再转发 |
secret_file | 数据目录 secrets/ 中的密钥文件名。文件不存在时,pwikit 将在启动时生成 |
挂载对实例上的所有站点生效。请将密钥文件的内容配置给该程序。
读者身份
读者已登录时,转发的请求带有 X-Pwikit-User 请求头,值为 <正文>.<签名>:
- 正文是 JSON 对象的 base64url 编码(无填充),包含
id、username、name、site与exp,读者是超级管理员时还包含"superuser": true; - 签名是使用密钥对正文计算的 HMAC-SHA256,以十六进制表示。
exp 为签发后一分钟的 Unix 时间。程序应先校验签名与 exp,再信任其中的身份。
发送通知
程序可以向读者发送通知,通知显示在读者的「通知」中:
POST /pw-api/mounts/notify
X-Pwikit-Mount: /scpper/
X-Pwikit-Signature: <请求体的 HMAC-SHA256,十六进制>
Content-Type: application/json
{"users": [12, 34], "title": "收到打赏", "message": "……", "link": "/scp-cn-001"}请求发往站点自身的地址,签名使用同一密钥。users 为用户编号,最多 500 个;title 最长 100 字;message 最长 2000 字,按纯文本显示;link 可省略,填写时须为本站路径。成功时返回 204。
读取站点数据
程序需要页面、评分等数据时,可以直接读取 pwikit 的数据库。
使用自有 PostgreSQL 时,请为程序创建 pwikit 数据库的只读账号。
使用内置 PostgreSQL 时,连接方式因系统而异,端口均记录在数据目录下的 pgdata/pwikit.conf 中:
Linux 与 macOS。 内置 PostgreSQL 仅通过
pgdata/中的套接字接受连接,且仅接受pgdata/的所有者账户与 root。请以该账户运行程序,并使用pgdata/pwikit.role中记录的数据库角色连接:textpostgres://<角色>@/pwikit?host=/opt/pwikit/pgdata&port=<端口>Windows。 内置 PostgreSQL 监听
127.0.0.1,用户名为pwikit,密码位于secrets/postgres-password:textpostgres://pwikit:<密码>@127.0.0.1:<端口>/pwikit
以上账号对数据库拥有完整权限,请仅交给可信的程序使用。
示例:部署 scpper
scpper 为站点提供云币、抽卡和分部指数。以下步骤假定 pwikit 在 Linux 上安装于 /opt/pwikit 并使用内置 PostgreSQL,scpper 安装于 /opt/scpper。
查询以下几项,后续步骤中将用到:
shstat -c %U /opt/pwikit/pgdata # 运行 scpper 的账户 sudo cat /opt/pwikit/pgdata/pwikit.role # 数据库角色 sudo grep port /opt/pwikit/pgdata/pwikit.conf sudo -u <账户> /opt/pwikit/pwikit site list # 站点标识名在
pwikit.toml中添加配置一节中的[[mount]],然后重启 pwikit:shsudo /opt/pwikit/pwikit service restart重启后,
/opt/pwikit/secrets/mount-scpper.key将自动生成。安装 PostgreSQL 客户端,为 scpper 创建数据库:
shsudo apt install postgresql-client sudo -u <账户> psql "host=/opt/pwikit/pgdata port=<端口> dbname=pwikit user=<角色>" -c "CREATE DATABASE scpper"连接时须指定
user=<角色>,否则将出现Peer authentication failed。下载 scpper 并添加执行权限:
shsudo mkdir -p /opt/scpper sudo wget -O /opt/scpper/scpper https://github.com/scpwikicloud/scpper/releases/latest/download/scpper_linux_amd64 sudo chmod +x /opt/scpper/scpper在同一目录创建
.env:shDATABASE_URL=postgres://<角色>@/scpper?host=/opt/pwikit/pgdata&port=<端口> PWIKIT_DATABASE_URL=postgres://<角色>@/pwikit?host=/opt/pwikit/pgdata&port=<端口> PWIKIT_SITE=<站点标识名> PWIKIT_SECRET_FILE=/opt/pwikit/secrets/mount-scpper.key HTTP_ADDR=127.0.0.1:8100 PWIKIT_URL=https://<站点域名>然后执行
sudo chown -R <账户>:<账户> /opt/scpper。创建
/etc/systemd/system/scpper.service:ini[Unit] Description=scpper After=network.target [Service] User=<账户> WorkingDirectory=/opt/scpper ExecStart=/opt/scpper/scpper serve Restart=on-failure [Install] WantedBy=multi-user.targetshsudo systemctl daemon-reload sudo systemctl enable --now scpper journalctl -u scpper -f日志中出现
scpper serve与sync pwikit即表示 scpper 已启动并连接到 pwikit 的数据库。若出现Permission denied,请检查第 4 步的执行权限,然后运行sudo systemctl reset-failed scpper与sudo systemctl restart scpper。访问
https://<站点域名>/scpper/。超级管理员访问时将自动成为 scpper 的管理员。
在个人主页显示云币、在页面中使用财富榜和打赏按钮,需要另外安装 scpper 插件,见插件。
更新 scpper 时,运行 sudo -u <账户> /opt/scpper/scpper update,然后执行 sudo systemctl restart scpper。
pwikit backup create 不包含 scpper 的数据库,请另行备份:
sudo -u <账户> pg_dump "host=/opt/pwikit/pgdata port=<端口> dbname=scpper user=<角色>" > scpper.sql