2026年6月11日 (四) 11:25 Doge24190

2026-06-11T11:25:31Z

←上一版本		2026年6月11日 (四) 19:25的版本
第252行：		第252行：

	完成这两步后，DokuWiki 的 <abbr>URL</abbr> 重写、媒体文件、Logo 和缩略图都恢复正常。		完成这两步后，DokuWiki 的 <abbr>URL</abbr> 重写、媒体文件、Logo 和缩略图都恢复正常。
			[[分类:技术博客]]
			[[分类:Dokuwiki]]
			[[分类:Nginx]]

Doge24190：创建页面，内容为“最近我在给自己的 DokuWiki 配置 URL 重写，也就是让原本类似： /doku.php?id=start 这样的地址变成更简洁的： /start 配置过程中，页面本身很快就能正常访问了，但随后遇到了一个比较隐蔽的问题：'''上传的媒体文件、网站 Logo 和部分缩略图无法正常显示'''。这篇文章记录一下完整排查过程和最终解决方案。 ---- == 一、环境说明 == 我的 DokuWiki…”

2026-06-11T11:24:15Z

创建页面，内容为“最近我在给自己的 DokuWiki 配置 <abbr>URL</abbr> 重写，也就是让原本类似： /doku.php?id=start 这样的地址变成更简洁的： /start 配置过程中，页面本身很快就能正常访问了，但随后遇到了一个比较隐蔽的问题：'''上传的媒体文件、网站 Logo 和部分缩略图无法正常显示'''。这篇文章记录一下完整排查过程和最终解决方案。 ---- == 一、环境说明 == 我的 DokuWiki…”

新页面

最近我在给自己的 DokuWiki 配置 <abbr>URL</abbr> 重写，也就是让原本类似：
/doku.php?id=start
这样的地址变成更简洁的：
/start
配置过程中，页面本身很快就能正常访问了，但随后遇到了一个比较隐蔽的问题：'''上传的媒体文件、网站 Logo 和部分缩略图无法正常显示'''。

这篇文章记录一下完整排查过程和最终解决方案。
----

== 一、环境说明 ==
我的 DokuWiki 安装路径为：
/www/wwwroot/dokuwiki
媒体文件实际存放路径为：
/www/wwwroot/dokuwiki/data/media
网站使用：Nginx + PHP + DokuWiki + Cloudflare

DokuWiki 媒体文件并不是直接通过 <code>/data/media/xxx.png</code> 访问，而是通过 DokuWiki 的 PHP 程序处理，例如：
/_media/logo.png
最终会被重写到：
/lib/exe/fetch.php?media=logo.png
这点非常重要，不能为了让图片能访问就直接开放 <code>/data/media</code> 目录。
----

== 二、最初的 Nginx 重写规则 ==
我最初添加了类似下面的规则：
location / {
try_files $uri $uri/ @dokuwiki;
}

location @dokuwiki {
rewrite ^/_media/(.*) /lib/exe/fetch.php?media=$1 last;
rewrite ^/_detail/(.*) /lib/exe/detail.php?media=$1 last;
rewrite ^/_export/([^/]+)/(.*) /doku.php?do=export_$1&id=$2 last;
rewrite ^/(.*) /doku.php?id=$1&$args last;
}
页面访问没有问题，但媒体文件无法访问。

后来发现，问题出在 Nginx 的静态资源缓存规则上。

配置里还有这样的规则：
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
{
expires 30d;
error_log /dev/null;
access_log /dev/null;
}
而 DokuWiki 的媒体 <abbr>URL</abbr> 是这样的：
/_media/logo.png
因为它以 <code>.png</code> 结尾，所以请求会被上面的图片缓存规则提前匹配，Nginx 会尝试直接寻找：
/www/wwwroot/dokuwiki/_media/logo.png
但实际文件并不在这个位置，而是在：
/www/wwwroot/dokuwiki/data/media/logo.png
因此返回 404。
----

== 三、修复媒体文件无法访问 ==
解决方法是：'''给 <code>/_media/</code>、<code>/_detail/</code>、<code>/_export/</code> 单独写高优先级 location，并放在静态资源缓存规则之前。'''

最终使用的规则如下：
location ^~ /_media/ {
rewrite ^/_media/(.*)$ /lib/exe/fetch.php?media=$1 last;
}

location ^~ /_detail/ {
rewrite ^/_detail/(.*)$ /lib/exe/detail.php?media=$1 last;
}

location ^~ /_export/ {
rewrite ^/_export/([^/]+)/(.*)$ /doku.php?do=export_$1&id=$2 last;
}

location / {
try_files $uri $uri/ @dokuwiki;
}

location @dokuwiki {
rewrite ^/(.*) /doku.php?id=$1&$args last;
}
这里使用了：
^~
表示只要匹配到这个前缀，就不再继续匹配后面的正则 location。

这样 <code>/_media/logo.png</code> 就不会被图片缓存规则截走，而是会正确交给 DokuWiki 的 <code>fetch.php</code> 处理。
----

== 四、不要直接开放 data 目录 ==
DokuWiki 的 <code>data</code>、<code>conf</code>、<code>inc</code>、<code>vendor</code> 等目录不应该被外部直接访问。

可以保留这样的安全规则：
location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md|data|conf|bin|inc|vendor)
{
return 404;
}
这样可以防止访问：
/data/media/logo.png
/conf/local.php
/inc/
媒体文件应通过：
/_media/logo.png
由 DokuWiki 控制输出。
----

== 五、Logo 和缩略图仍然无法显示 ==
媒体文件可以直接打开后，我又遇到了第二个问题。

页面中的 Logo 和缩略图仍然无法显示，例如：
<'''img''' id="dw__logo" src="/_media/logo.png">
以及：
<'''img''' src="/_media/capture_2025-11-11_185838.png?w=90&h=90&tok=68fe3f">
但奇怪的是，某些带参数的图片又可以访问：
/_media/logo.png?t=1706014361&w=64&h=64&tok=e2dbf1
为了进一步判断问题，我在终端使用 `curl -I` 测试了几个地址：
curl -I "<nowiki>https://www.example.com/_media/logo.png</nowiki>"
curl -I "<nowiki>https://www.example.com/_media/logo.png?t=1706014361&w=64&h=64&tok=e2dbf1</nowiki>"
curl -I "<nowiki>https://www.example.com/lib/exe/fetch.php?media=logo.png</nowiki>"
curl -I "<nowiki>https://www.example.com/lib/exe/fetch.php?media=logo.png&t=1706014361&w=64&h=64&tok=e2dbf1</nowiki>"
结果发现：
/_media/logo.png
返回：
HTTP/2 404
cf-cache-status: HIT
而：
/lib/exe/fetch.php?media=logo.png
返回：
HTTP/2 200
content-type: image/png
这说明源站和 DokuWiki 本身已经正常，真正的问题是：'''Cloudflare 缓存了之前的 404 页面。'''

== 六、最终解决：清理 Cloudflare 缓存 ==
进入 Cloudflare 后台：
缓存 → 配置 → 清除所有内容
清理后再次测试：
curl -I "<nowiki>https://www.example.com/_media/logo.png</nowiki>"
返回变成：
HTTP/2 200
content-type: image/png
此时 Logo 和缩略图也恢复正常。
----

== 七、最终推荐配置片段 ==
下面是最终比较稳定的 DokuWiki Nginx 伪静态配置片段：
''# 禁止访问敏感文件和目录''
location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md|data|conf|bin|inc|vendor)
{
return 404;
}

''# SSL 证书验证目录''
location ^~ /.well-known/ {
allow all;
}

''# DokuWiki 媒体文件''
location ^~ /_media/ {
rewrite ^/_media/(.*)$ /lib/exe/fetch.php?media=$1 last;
}

location ^~ /_detail/ {
rewrite ^/_detail/(.*)$ /lib/exe/detail.php?media=$1 last;
}

location ^~ /_export/ {
rewrite ^/_export/([^/]+)/(.*)$ /doku.php?do=export_$1&id=$2 last;
}

''# DokuWiki 页面 URL 重写''
location / {
try_files $uri $uri/ @dokuwiki;
}

location @dokuwiki {
rewrite ^/(.*) /doku.php?id=$1&$args last;
}

''# 静态图片缓存''
location ~* \.(gif|jpg|jpeg|png|bmp|swf|webp|svg|ico)$
{
expires 30d;
error_log /dev/null;
access_log off;
}

''# JS/CSS 缓存''
location ~* \.(js|css)$
{
expires 12h;
error_log /dev/null;
access_log off;
}
修改完成后检查配置并重载 Nginx：
----

== 八、DokuWiki 后台配置 ==
DokuWiki 后台还需要开启 <abbr>URL</abbr> 重写。

进入：管理 → 配置设置 → 高级设置

设置：

使用更整洁的URL<code>userewrite</code> 为<code>.htaccess</code> 启用在 <abbr>URL</abbr> 中使用斜杠作为命名空间的分隔符<code>useslash</code>
----

== 九、排查经验总结 ==
这次问题主要分为三个阶段：

第一，页面 <abbr>URL</abbr> 重写正常，但媒体文件 404。

原因是 <code>/_media/*.png</code> 被 Nginx 的图片缓存 location 提前匹配，导致 Nginx 直接去文件系统寻找 <code>/_media/</code> 目录。

解决方法是给 <code>/_media/</code> 单独写：
location ^~ /_media/
并放在图片缓存规则之前。

第二，媒体文件直接访问恢复，但 Logo 和缩略图仍然异常。

这时需要用 <code>curl -I</code> 分别测试：
/_media/logo.png
/lib/exe/fetch.php?media=logo.png
如果 <code>fetch.php</code> 能返回 200，说明 DokuWiki 正常，问题不在 PHP 层。

第三，发现 Cloudflare 返回的是旧的 404 缓存。

判断依据是响应头里出现：
cf-cache-status: HIT
age: xxxx
HTTP/2 404
说明请求甚至没有回到源站，而是 Cloudflare 直接返回了缓存结果。

最终清理 Cloudflare 缓存后，问题全部解决。
----

== 十、结论 ==
DokuWiki 配置 <abbr>URL</abbr> 重写时，媒体文件无法显示并不一定是 DokuWiki 本身的问题，常见原因有：
Nginx location 匹配顺序错误
静态资源缓存规则截走了 /_media/ 请求
Cloudflare 缓存了旧的 404
DokuWiki 页面缓存或缩略图缓存未刷新
排查时不要只看浏览器页面显示效果，最好用：<code>curl -I</code>

分别检查：
/_media/xxx.png
/lib/exe/fetch.php?media=xxx.png
这样可以快速判断问题到底出在：
Nginx 重写
DokuWiki PHP 处理
Cloudflare 缓存
浏览器缓存
这次最终的关键点在于

# Nginx 使用 ^~ /_media/ 防止媒体请求被静态图片规则截走
# Cloudflare 清理旧的 404 缓存

完成这两步后，DokuWiki 的 <abbr>URL</abbr> 重写、媒体文件、Logo 和缩略图都恢复正常。

Dokuwiki URL重写 - 版本历史

2026年6月11日 (四) 11:25 Doge24190