feat: serve styled mirror directories with nginx fancyindex

This commit is contained in:
2026-11-01 20:37:13 +08:00
parent 706ed6faf1
commit d3a5e99e8a
18 changed files with 597 additions and 14 deletions
+11 -1
View File
@@ -73,7 +73,15 @@ HTTPS/rsync 使用 TCP 443/873 的 IPv4、IPv6 收发字节计数,双向
NFS I/O 来自 `/proc/self/mountstats` 的 `/data` 挂载,磁盘容量来自 statvfs;CPU、内存来自 `/proc`。采样历史仅覆盖采集器启用后的时间,不补造旧数据。图表最多展示 241 个采样点,均值、当前值、峰值从当前窗口全部原始有效采样计算。
镜像文件由 Nginx 直接提供,API 不读取整个仓库;镜像目录响应设置 CSP sandbox 和 nosniff,避免仓库中的 HTML/脚本获得管理页面同源权限。
目录 HTML、静态资源和文件下载全部由 Nginx 提供,Go 不参与目录遍历或文件传输。需要与当前 Nginx ABI 匹配的 Fancyindex 模块及内置 addition、sub_filter 模块;当前 Debian 13 使用 `apt-get install libnginx-mod-http-fancyindex`,安装后执行 `nginx -t`。自编译 Nginx 必须安装匹配模块,不要用包管理器覆盖现有二进制。主配置须加载模块(Debian 的 `/etc/nginx/modules-enabled/*.conf`)。
`npm run build` 使用独立 Vite 入口 `directory.html`,随后生成 `dist/fancy-index/header.html`、`footer.html` 和 `labels.conf`。Fancyindex 内部子请求插入页头和页脚,`sub_filter` 用语言文件生成的文案替换四个原生英文标签。浏览器首次响应已经包含全部文件条目;无需 JavaScript、Go 或 JSON 即可导航和下载。JS 只增加搜索、每页 100 条、面包屑、主题、语言和一次可选的站点设置加载。无 JS 时默认中文,显示全部条目。目录 GET/HEAD 只读、目录优先、隐藏项省略,时间显示 UTC;表头的排序链接由 Fancyindex 在服务端处理。
目录正则 location 的 `alias /data/mirrors/$mirror_directory` 与下载 location 的 `alias /data/mirrors/` 指向同一镜像树;符号链接遵循 Nginx 和文件系统访问规则,镜像树应仅包含可公开分发的内容。`/mirrors/` 重定向首页,因此仓库根目录的原生上级链接也会返回首页。目录仍需读取当前层文件元数据,不递归扫描;服务端 HTML 不会消除 NFS 元数据开销,大目录首访延迟仍需单独监测。
文件响应继续设置 CSP sandbox 和 nosniff,避免仓库中的 HTML/脚本获得管理页面同源权限。目录 HTML 使用主站 CSP,两个模板子请求入口为 `internal`,不能直接访问。仓库中的 `index.html` 不会替代目录列表;显式访问它仍走文件下载 location,保留 sandbox、HEAD 和 Range。
发布时同时更新整个 `dist/` 和 `nginx-preview.conf`,保证 `labels.conf` 在 `nginx -t` 时已经存在。执行检查后 reload Nginx;只有前端和目录变化时不必重启 Go 或 tunasync。旧 `/api/v1/directory/` 已移除,原 `MIRROROUC_MIRRORS` 环境变量不再使用。不重新初始化数据库或修改同步任务,原有 80 端口站点保持原配置。回退时同时恢复站点配置与发布目录软链接,并重新检查、reload。
## 备份与回退
@@ -89,6 +97,8 @@ NFS I/O 来自 `/proc/self/mountstats` 的 `/data` 挂载,磁盘容量来自 s
本次部署核验真实 API、镜像目录、日志、监控与后台草稿保存。没有为验证效果而停止、重启仓库,或应用修改后的生产同步参数。
先运行 `npm run build && npm run check:directory`,再在安装 Fancyindex 的 Linux 上运行 `python3 deploy/test_nginx_directory.py`。测试使用临时文件与独立本地端口,Go 上游故意不可用,验证原始 HTML 包含条目、中英文标签模板、排序、特殊文件名转义、空/不存在目录、仓库 index.html、HEAD/Range、只读限制、内部模板隔离和路径边界;不停止真实服务或修改真实镜像目录。
## 统一中文内容升级
公告的 title/body 和镜像的 help 已改为单个字符串,所有界面语言共用中文内容。旧版本的语言映射在服务启动时以事务迁移:优先保留 zh-CN,其次 zh;没有中文键的历史记录保留原内容供管理员整理。原始 JSON 保存在 SQLite 的 shared_content_backups 表,迁移会递增记录 revision,避免旧编辑页面覆盖新内容;重复启动不会重复迁移。
+7
View File
@@ -5,6 +5,13 @@ release=$(readlink -f "$1")
case "$release" in /opt/mirrorouc/releases/*) ;; *) echo 'Invalid release path' >&2; exit 1;; esac
test -x "$release/mirrorouc"
test -f "$release/dist/index.html"
test -f "$release/dist/fancy-index/header.html"
test -f "$release/dist/fancy-index/footer.html"
# The module must match the installed Nginx ABI; do not replace a custom build.
if ! nginx -T 2>&1 | grep -q 'load_module.*ngx_http_fancyindex_module'; then
echo 'Install and enable a matching Nginx Fancyindex module first (Debian: apt-get install libnginx-mod-http-fancyindex).' >&2
exit 1
fi
deploy="$release/deploy"
id mirrorouc >/dev/null 2>&1 || useradd --system --home-dir /var/lib/mirrorouc --shell /usr/sbin/nologin mirrorouc
install -d -m 0700 -o mirrorouc -g mirrorouc /var/lib/mirrorouc
+48 -3
View File
@@ -3,11 +3,56 @@ server {
server_name 100.69.2.2;
client_max_body_size 5m;
location = /mirrors {
return 302 /;
}
location = /mirrors/ {
return 302 /;
}
location /assets/ {
root /opt/mirrorouc/current/dist;
try_files $uri =404;
add_header X-Content-Type-Options nosniff always;
}
# Fancyindex renders the complete directory on the server. No Go/JSON hop.
location ~ ^/mirrors/(?<mirror_directory>.+/)$ {
alias /data/mirrors/$mirror_directory;
index .mirrorouc-autoindex-only;
fancyindex on;
fancyindex_header /_directory/header.html;
fancyindex_footer /_directory/footer.html;
fancyindex_show_path off;
fancyindex_name_length 256;
fancyindex_exact_size off;
fancyindex_directories_first on;
fancyindex_show_dotfiles off;
fancyindex_localtime off;
fancyindex_time_format "%Y-%m-%d %H:%M:%S UTC";
include /opt/mirrorouc/current/dist/fancy-index/labels.conf;
charset utf-8;
limit_except GET { deny all; }
add_header Cache-Control no-cache;
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options DENY always;
add_header Referrer-Policy same-origin always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'" always;
}
# Only Fancyindex subrequests may read the generated fragments.
location = /_directory/header.html {
internal;
alias /opt/mirrorouc/current/dist/fancy-index/header.html;
}
location = /_directory/footer.html {
internal;
alias /opt/mirrorouc/current/dist/fancy-index/footer.html;
}
location /mirrors/ {
alias /data/mirrors/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
autoindex off;
add_header X-Content-Type-Options nosniff always;
add_header Content-Security-Policy "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:" always;
}
+151
View File
@@ -0,0 +1,151 @@
"""Exercise the shipped Nginx routes using disposable files and an isolated port."""
from html.parser import HTMLParser
from pathlib import Path
import shutil
import socket
import subprocess
import tempfile
import time
import unittest
import urllib.error
import urllib.parse
import urllib.request
class NginxDirectoryTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
nginx = shutil.which('nginx')
if not nginx:
raise unittest.SkipTest('Nginx is required for the integration fixture')
cls.temp = tempfile.TemporaryDirectory(prefix='mirrorouc-nginx-test-')
cls.root = Path(cls.temp.name)
cls.mirrors = cls.root / 'mirrors'
cls.dist = cls.root / 'dist'
(cls.mirrors / 'repo' / 'sub').mkdir(parents=True)
(cls.mirrors / 'repo' / 'empty').mkdir()
build = Path(__file__).resolve().parent.parent / 'dist'
if not (build / 'fancy-index' / 'header.html').is_file():
raise RuntimeError('Run npm run build before the Nginx integration fixture')
shutil.copytree(build, cls.dist)
(cls.dist / 'assets' / 'test.js').write_text('window.fixture = true', encoding='utf-8')
(cls.mirrors / 'repo' / 'index.html').write_text('repository index must not replace listing', encoding='utf-8')
(cls.mirrors / 'repo' / '中文 #+%.txt').write_bytes(b'0123456789abcdef')
(cls.mirrors / 'repo' / 'zero').write_bytes(b'')
(cls.mirrors / 'repo' / '.hidden').write_text('hidden', encoding='utf-8')
(cls.mirrors / 'repo' / '\"><img src=x onerror=alert(1)>.txt').write_text('escaped name', encoding='utf-8')
(cls.root / 'private-secret').write_text('outside-secret', encoding='utf-8')
with socket.socket() as available:
available.bind(('127.0.0.1', 0))
port = available.getsockname()[1]
cls.base = f'http://127.0.0.1:{port}'
server = Path(__file__).with_name('nginx-preview.conf').read_text(encoding='utf-8')
server = server.replace('listen 100.69.2.2:8080;', f'listen 127.0.0.1:{port};')
server = server.replace('/data/mirrors/', cls.mirrors.as_posix() + '/')
server = server.replace('/opt/mirrorouc/current/dist', cls.dist.as_posix())
# The Go upstream is deliberately unavailable throughout these tests.
server = server.replace('http://127.0.0.1:8081', 'http://127.0.0.1:9')
config = cls.root / 'nginx.conf'
config.write_text(f'load_module /usr/lib/nginx/modules/ngx_http_fancyindex_module.so;\nworker_processes 1;\npid {cls.root}/nginx.pid;\nerror_log {cls.root}/error.log;\nevents {{ worker_connections 32; }}\nhttp {{ access_log off; types {{ text/html html; text/plain txt; application/javascript js; }}\n{server}\n}}\n', encoding='utf-8')
validation = subprocess.run([nginx, '-p', str(cls.root), '-c', str(config), '-t'], capture_output=True, text=True)
if validation.returncode:
raise RuntimeError(validation.stderr)
cls.process = subprocess.Popen([nginx, '-p', str(cls.root), '-c', str(config), '-g', 'daemon off; master_process off;'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
for _ in range(100):
if cls.process.poll() is not None:
raise RuntimeError((cls.root / 'error.log').read_text())
try:
with urllib.request.urlopen(cls.base + '/assets/test.js', timeout=1):
return
except (OSError, urllib.error.URLError):
time.sleep(0.03)
cls.process.terminate()
raise RuntimeError('Isolated Nginx did not become ready')
@classmethod
def tearDownClass(cls):
cls.process.terminate()
cls.process.wait(timeout=5)
cls.temp.cleanup()
def request(self, path, method='GET', headers=None):
request = urllib.request.Request(self.base + path, method=method, headers=headers or {})
try:
response = urllib.request.build_opener(NoRedirect).open(request, timeout=5)
except urllib.error.HTTPError as response:
return response.code, response.headers, response.read()
with response:
return response.status, response.headers, response.read()
def test_complete_server_html_without_go_or_javascript(self):
code, headers, body = self.request('/mirrors/repo/')
self.assertEqual(code, 200)
self.assertIn('text/html', headers['Content-Type'])
html = body.decode('utf-8')
self.assertIn('<table id="list">', html)
self.assertIn('href="sub/"', html)
self.assertIn('href="index.html"', html)
self.assertIn('中文 #+%.txt', html)
self.assertIn('data-i18n="directory.name">文件名</span>', html)
self.assertIn('data-i18n="directory.parent">返回上级</span>', html)
self.assertIn('UTC', html)
self.assertIn('</footer>', html)
self.assertNotIn('{{', html)
self.assertNotIn('repository index must not replace listing', html)
self.assertNotIn('.hidden', html)
parsed = Tags(); parsed.feed(html)
self.assertFalse(any(tag == 'img' and attrs.get('onerror') for tag, attrs in parsed.tags))
self.assertNotIn('sandbox', headers['Content-Security-Policy'])
self.assertEqual(self.request('/assets/test.js')[0], 200)
self.assertEqual(self.request('/')[0], 502)
def test_files_still_support_range_and_head(self):
url = '/mirrors/repo/' + urllib.parse.quote('中文 #+%.txt', safe='')
code, headers, body = self.request(url, headers={'Range': 'bytes=1-4'})
self.assertEqual((code, body), (206, b'1234'))
self.assertEqual(headers['Content-Range'], 'bytes 1-4/16')
self.assertIn('sandbox', headers['Content-Security-Policy'])
self.assertEqual(headers['X-Content-Type-Options'], 'nosniff')
code, headers, body = self.request(url, method='HEAD')
self.assertEqual((code, int(headers['Content-Length']), body), (200, 16, b''))
def test_empty_missing_internal_and_parent(self):
code, _, body = self.request('/mirrors/repo/empty/')
self.assertEqual(code, 200)
self.assertIn(b'<table id="list">', body)
self.assertEqual(self.request('/mirrors/missing/')[0], 404)
self.assertEqual(self.request('/mirrors/repo/', method='POST')[0], 403)
self.assertEqual(self.request('/_directory/header.html')[0], 404)
self.assertEqual(self.request('/_directory/footer.html')[0], 404)
code, headers, _ = self.request('/mirrors/')
self.assertEqual(code, 302)
self.assertTrue(headers['Location'].endswith('/'))
code, _, body = self.request('/mirrors/%2e%2e/private-secret/')
self.assertNotEqual(code, 200)
self.assertNotIn(b'outside-secret', body)
def test_native_sort_links_and_head(self):
code, _, body = self.request('/mirrors/repo/?C=N&O=D')
self.assertEqual(code, 200)
html = body.decode('utf-8')
self.assertLess(html.index('href="sub/'), html.index('href="empty/'))
code, _, body = self.request('/mirrors/repo/', method='HEAD')
self.assertEqual((code, body), (200, b''))
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
class Tags(HTMLParser):
def __init__(self):
super().__init__()
self.tags = []
def handle_starttag(self, tag, attrs):
self.tags.append((tag, dict(attrs)))
if __name__ == '__main__':
unittest.main()