Genarch Documentation docs
Projects / Wikipedia of Anhui Univ. Unofficial/ Development Technical Details
Guide

Development Technical Details

最后更新于 2026-07-22

部署指南

1. 前提

  • Debian 12/13、Ubuntu Server LTS 或兼容发行版
  • Docker Engine 与 Compose v2
  • 已运行的 Nginx 或衍生容器
  • 域名已解析到服务器
  • 管理电脑能够通过 SSH 登录服务器
  • 从 DokuWiki 官网下载的 .tgz 源码包

建议启用 1–2 GiB Swap，并保持至少 20% 磁盘空闲。

2. 准备项目

sudo mkdir -p /opt/longhe-wiki
sudo cp -a . /opt/longhe-wiki/
cd /opt/longhe-wiki

不要手工复制 README 中的示例哈希，也不要沿用其他人 .env 中的哈希。对你实际下载的包执行：

sh scripts/prepare-source.sh /path/to/dokuwiki.tgz
sh scripts/check.sh

脚本会生成：

dokuwiki.tgz   规范化后的源码包
.env           构建参数和本包 SHA-256
source.lock    便于审计、备份与恢复的锁定记录

如果之后源码包被替换或损坏，scripts/check.sh 和 Dockerfile 都会拒绝构建。

创建目录和网络：

mkdir -p config backups
sudo chown -R 33:33 config
sudo chown -R "$(id -u):$(id -g)" backups
docker network inspect proxy >/dev/null 2>&1 || docker network create proxy

若 NPM 网络不叫 proxy，编辑 .env 的 PROXY_NETWORK，并确保 NPM 容器加入该网络。

默认使用 DaoCloud 的 Docker Hub 前缀代理及中科大 Debian 镜像。镜像站不可用时，可在 .env 改回：

PHP_BASE_IMAGE=docker.io/library/php:8.3-apache-bookworm
DEBIAN_MIRROR=https://deb.debian.org/debian
DEBIAN_SECURITY_MIRROR=https://deb.debian.org/debian-security

3. 构建与首次安装

docker compose build --no-cache
docker compose up -d
docker compose ps
docker compose logs --tail=100 dokuwiki

端口只绑定 127.0.0.1:****。管理电脑建立 SSH 隧道：

ssh -L ****:127.0.0.1:**** root@服务器公网IP

打开：

http://127.0.0.1:****/install.php

安装时：

  1. Wiki 名称填写“**(Hidden) Wiki”；
  2. 启用 ACL；
  3. 创建随机强密码的初始管理员；
  4. 初始策略选择公开 Wiki，访客只读
  5. 在 .env 设置高强度 DOKUWIKI_INVITE_CODE，仅允许持邀请码的用户注册( 当前策略 )

完成后执行：

sudo sh scripts/bootstrap.sh
docker compose restart dokuwiki

容器重启时若检测到 config/dokuwiki/conf/local.php，会自动删除 /var/www/html/install.php。验证：

docker compose exec dokuwiki test ! -e /var/www/html/install.php

4. 配置 Nginx

创建 Proxy Host：

  • Domain Names：实际 Wiki 域名
  • Scheme：http
  • Forward Hostname/IP：longhe-wiki
  • Forward Port：**(Hidden)
  • Block Common Exploits：开启
  • SSL：申请证书，开启 Force SSL 与 HTTP/2

管理员仍必须使用强密码，并通过 SSH 隧道进行管理。

限流：

  1. 将 npm/rate-limit-http.conf 合并到 NPM 的 /data/nginx/custom/http.conf；
  2. 在容器内执行 nginx -t；
  3. 将 npm/rate-limit-server.conf 追加到 Proxy Host Advanced；
  4. 首周保留 dry-run；
  5. 确认不会误伤 NAT 后再关闭 dry-run。

不要直接覆盖已经存在的 http.conf。

5. 建立用户组

通过 SSH 隧道进入“管理 → 用户管理”，创建：

  • editor
  • reviewer
  • freshman-editor
  • life-editor
  • study-editor
  • transport-editor
  • organization-editor

6. 上线验收

分别使用访客、栏目编辑、审核者和管理员身份完成 docs/acceptance-checklist.md。验收完成后：

sh scripts/backup.sh

7. 升级

升级前备份。下载新官网包后重新执行：

sh scripts/prepare-source.sh /path/to/new-dokuwiki.tgz
sh scripts/check.sh
docker compose build --no-cache
docker compose up -d
sudo sh scripts/bootstrap.sh
docker compose restart dokuwiki