fx-file-server/README.md

FX File Server

一个轻量级文档管理与预览系统，基于 Hugo + Nginx + Filebrowser + OnlyOffice + Docker Compose。

1. 系统目标

• 统一文件入口：上传、浏览、检索、预览
• 多格式预览：pdf/docx/xlsx 等
• 前后端解耦：文档站点展示与文件管理分离
• 低运维成本：单机 docker-compose 一键部署

2. 架构与组件角色

2.1 核心服务

• filebrowser（文件管理核心）
  • 角色：文件上传、目录管理、权限控制
  • 对外端口：不直接暴露，通过代理访问
• filebrowser_proxy（文件管理前端代理，端口 8081）
  • 角色：UI主题定制、搜索页接入、OnlyOffice 预览跳转
  • 关键配置：filebrowser-proxy/default.conf
• onlyoffice（文档预览/编辑，端口 8090）
  • 角色：在线渲染 docx/xlsx/pptx
  • 关键配置：onlyoffice/local.json、onlyoffice/ds-docservice.conf
• nginx（文档门户与静态托管，端口 8080）
  • 角色：Hugo 产物发布、原始文件与预览页路由
  • 关键配置：nginx/default.conf
• hugo/build（站点构建）
  • 角色：文档网站编译、主题能力承载

2.2 可扩展组件

• converter/、word_converter/
  • 角色：文档离线转换（可选扩展，不是当前主路径）

3. 目录说明

• compose.yaml：主编排入口
• filebrowser/：Filebrowser 配置（如 settings.json）
• filebrowser-proxy/：Filebrowser 前端代理与自定义脚本
• onlyoffice/：OnlyOffice 配置
• nginx/：门户 nginx 配置
• site/：Hugo 站点源码
• hugo/：Hugo 构建镜像相关内容

4. 扩展性设计

• 存储扩展
  • 当前为本地 volume；可扩展到 NFS/对象存储挂载
• 身份与权限扩展
  • 现由 Filebrowser 提供用户权限；可接入反向代理统一认证（OIDC/SSO）
• 预览扩展
  • 当前由 OnlyOffice 处理 Office 文档；可按需新增 PDF/媒体专用服务
• 前端扩展
  • filebrowser-proxy/*.js 为低侵入注入式改造，便于迭代主题/交互

5. 安装指引（单机）

5.1 环境要求

• Linux 主机（推荐 Ubuntu 22.04+/Debian 12+）
• Docker 24+，Docker Compose v2+
• 建议 CPU >= 2C，内存 >= 4G（OnlyOffice 建议 8G）

5.2 快速部署

# 1) 拉代码
git clone http://47.92.55.118:3000/jiangkai/fx-file-server.git
cd fx-file-server

# 2) 启动核心服务
docker compose up -d filebrowser filebrowser_proxy onlyoffice nginx

# 3) 如需构建文档站
docker compose run --rm build

5.3 访问入口

• 文档门户：http://<HOST>:8080
• 文件管理：http://<HOST>:8081/files/
• OnlyOffice：http://<HOST>:8090

5.4 常用运维命令

# 查看服务状态
docker compose ps

# 查看某服务日志
docker compose logs -f filebrowser_proxy

# 重启代理（前端脚本更新后常用）
docker compose restart filebrowser_proxy

# 配置校验（容器内）
docker compose exec -T filebrowser_proxy nginx -t

6. 版本与变更建议

• 建议以 compose.yaml + proxy js 为变更主线
• 任何临时调试文件（.bak、backup-*）禁止入库
• 每次 UI/路由改动后执行：
  • docker compose restart filebrowser_proxy
  • 浏览器强刷（Ctrl+F5）

7. 安全建议

• 生产环境建议仅开放必要端口
• OnlyOffice 建议启用 JWT 并配置可信来源
• 建议在外层加 TLS 反向代理（Nginx/Caddy/Traefik）