Skip to content

挂载外部程序 ​

pwikit 可以将站点下的一个路径转发给同一台机器上的其他程序,例如将 /scpper/ 交给 scpper。读者访问的仍是同一个站点,登录状态由 pwikit 告知该程序。

配置 ​

在 pwikit.toml 中为每个程序添加一段 [[mount]],然后重启 pwikit:

toml
[[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,再信任其中的身份。

发送通知 ​

程序可以向读者发送通知,通知显示在读者的「通知」中:

text
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 中记录的数据库角色连接:

    text
    postgres://<角色>@/pwikit?host=/opt/pwikit/pgdata&port=<端口>
  • Windows。 内置 PostgreSQL 监听 127.0.0.1,用户名为 pwikit,密码位于 secrets/postgres-password:

    text
    postgres://pwikit:<密码>@127.0.0.1:<端口>/pwikit

以上账号对数据库拥有完整权限,请仅交给可信的程序使用。

示例:部署 scpper ​

scpper 为站点提供云币、抽卡和分部指数。以下步骤假定 pwikit 在 Linux 上安装于 /opt/pwikit 并使用内置 PostgreSQL,scpper 安装于 /opt/scpper。

  1. 查询以下几项,后续步骤中将用到:

    sh
    stat -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  # 站点标识名
  2. 在 pwikit.toml 中添加配置一节中的 [[mount]],然后重启 pwikit:

    sh
    sudo /opt/pwikit/pwikit service restart

    重启后,/opt/pwikit/secrets/mount-scpper.key 将自动生成。

  3. 安装 PostgreSQL 客户端,为 scpper 创建数据库:

    sh
    sudo apt install postgresql-client
    sudo -u <账户> psql "host=/opt/pwikit/pgdata port=<端口> dbname=pwikit user=<角色>" -c "CREATE DATABASE scpper"

    连接时须指定 user=<角色>,否则将出现 Peer authentication failed。

  4. 下载 scpper 并添加执行权限:

    sh
    sudo 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:

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

  5. 创建 /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.target
    sh
    sudo 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。

  6. 访问 https://<站点域名>/scpper/。超级管理员访问时将自动成为 scpper 的管理员。

在个人主页显示云币、在页面中使用财富榜和打赏按钮,需要另外安装 scpper 插件,见插件。

更新 scpper 时,运行 sudo -u <账户> /opt/scpper/scpper update,然后执行 sudo systemctl restart scpper。

pwikit backup create 不包含 scpper 的数据库,请另行备份:

sh
sudo -u <账户> pg_dump "host=/opt/pwikit/pgdata port=<端口> dbname=scpper user=<角色>" > scpper.sql