🖥️ 上海服务器 Web 服务规范

sh.kibox.com.cn:8080 · nginx 管理 · File Browser 网盘

目录 1. 服务概览 2. 目录结构 3. 首页维护规范 4. 静态子目录挂载 5. 反向代理子服务挂载 6. 文件下载链接管理 7. 网盘（File Browser） 8. nginx 配置参考 9. 日常维护

1. 服务概览

项值
端口8080
Web 根目录/var/www/html
nginx 配置/etc/nginx/sites-enabled/glm-grabber
首页/var/www/html/index.html
网盘存储/var/www/html/netdisk/
网盘服务File Browser v2.63.2 → 127.0.0.1:8082
公网地址http://sh.kibox.com.cn/
所有子服务通过 nginx 统一入口访问，公网只能接触 8080 端口，内部服务的防火墙策略互不影响。

2. 目录结构

/var/www/html/ ├── index.html ← 8080 首页（服务导航） ├── netdisk/ ← 网盘存储目录（File Browser 挂载点） ├── gba-naruto/ ← 静态子服务（nginx alias 模式） │ └── index.html ← SPA 入口 ├── SAO/ ← 静态子服务（同上） │ └── index.html ├── research/ ← 调研报告（直接静态文件） └── pets/ ← 代理到 :8081（第三方宠物图鉴）
所有需要提供下载的文件（ZIP、ROM、文档等）必须放到 /var/www/html/netdisk/，不可直接放在根目录或子目录中。

3. 首页维护规范

首页位置

/var/www/html/index.html

直接编辑此文件即可更新首页。格式为标准 HTML + CSS，无需重启 nginx。

卡片格式模板

<a href="/子路径/" class="card"> <h3>图标 + 服务名</h3> <p>简短描述</p> <span class="tag">标签</span> </a>

图标推荐用 Emoji，标签填写服务类型（工具/自动化/数据等）。

添加新服务入口

在 <div class="services"> 内任意位置插入上方的卡片模板即可。 添加完成后无需重启 nginx，直接刷新页面即可生效。

页脚说明文档链接

页脚已添加本规范的链接： <a href="/SPEC.html">📖 服务规范</a> 更新首页时保留此链接即可。

4. 静态子目录挂载（nginx alias 模式）

适用于前端构建产物（Vite/Webpack 输出目录）。特点：URL 路径和文件系统路径一致。

配置步骤

  1. 将构建产物放入 /var/www/html/你的子目录/
  2. 编辑 /etc/nginx/sites-enabled/glm-grabber，添加 location 块（参考下方模板）
  3. nginx -t 验证语法
  4. nginx -s reload 重载配置
  5. 在 index.html 添加导航卡片

nginx 配置模板（静态子目录）

location /你的子路径/ { alias /var/www/html/你的子目录/; try_files $uri $uri/ /你的子路径/index.html; }
如果子服务是 SPA（单页应用），try_files 一定要加 /你的子路径/index.html fallback，否则刷新页面会 404。

5. 反向代理子服务挂载

适用于已有独立服务进程（Node/FastAPI/Python 等）运行在本地端口上。

配置步骤

  1. 确保服务运行在 127.0.0.1:端口
  2. 编辑 /etc/nginx/sites-enabled/glm-grabber，添加 location 块（参考下方模板）
  3. nginx -t && nginx -s reload
  4. 在 index.html 添加导航卡片

nginx 配置模板（反向代理）

location /子路径/ { proxy_pass http://127.0.0.1:你的端口/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_buffering off; }

注意：末尾的 / 会剥离 URL 前缀。如需保留前缀，用 rewrite 手动处理。

6. 文件下载链接管理

⚠️ 所有需要下载的文件（ROM、压缩包、报告等）必须上传到网盘存储目录，不允许直接放在 /var/www/html/ 下。

正确流程

  1. 将文件 cp 或上传到 /var/www/html/netdisk/
  2. 在 File Browser Web UI 中创建公开分享链接（或在首页用网盘路径引用）
  3. 在 index.html 中用普通 <a> 链接指向网盘文件 URL

网盘文件 URL 格式

http://sh.kibox.com.cn/netdisk/s/分享ID

File Browser 的分享链接格式。也可以直接链接到：http://sh.kibox.com.cn/netdisk/文件路径（需登录）

调研报告（/research/*.md）目前直接静态托管，如文件变大建议迁移到网盘。

7. 网盘（File Browser）

项值
访问地址http://sh.kibox.com.cn/netdisk/
存储目录/var/www/html/netdisk/
服务进程systemd: filebrowser（127.0.0.1:8082）
管理员账号kibox
断点续传✅ TUS 协议，10MB 分块
配置文件/opt/filebrowser/filebrowser
数据库/opt/filebrowser/data/filebrowser.db

常用管理命令

# 重启网盘服务 systemctl restart filebrowser # 查看运行状态 systemctl status filebrowser # 查看实时日志 journalctl -u filebrowser -f

添加文件到网盘（服务器端）

# 方式一：直接复制（最快） cp /path/to/file.zip /var/www/html/netdisk/ # 方式二：File Browser CLI /opt/filebrowser/filebrowser upload file.zip --database /opt/filebrowser/data/filebrowser.db /netdisk/

8. nginx 配置参考

当前所有 location 汇总

路径类型目标
/静态/var/www/html（try_files index.html）
/netdisk/反向代理127.0.0.1:8082（File Browser）
/gba-naruto/静态 alias/var/www/html/gba-naruto/
/gba-naruto/api/反向代理127.0.0.1:8000
/SAO/反向代理127.0.0.1:18081
/grab/反向代理127.0.0.1:18080
/pets/反向代理127.0.0.1:8081

配置文件位置

主配置: /etc/nginx/nginx.conf 站点配置: /etc/nginx/sites-enabled/glm-grabber ← 8080 端口所有 location 在这里 模块配置: /etc/nginx/modules-enabled/*.conf

9. 日常维护

添加新子服务检查清单

  1. 确认服务运行在 127.0.0.1:端口（静态文件则确认路径在 /var/www/html/ 下）
  2. 在 nginx 配置添加对应的 location 块
  3. nginx -t 验证通过
  4. nginx -s reload 重载
  5. 在 index.html 添加导航卡片
  6. 在本规范文档（/SPEC.html）更新对应章节

常用运维命令

# nginx 配置重载（推荐） nginx -s reload # nginx 强制重载（配置未生效时） systemctl reload nginx # 完全重启 nginx systemctl restart nginx # 检查配置语法 nginx -t # 查看 nginx 进程 ps aux | grep nginx