File Viewer 部署与配置笔记

一、需求概述

在云服务器上使用 Podman 部署 Caddy，通过域名访问并在线查看服务器上的 .xmind 文件，仅需查看功能，无需编辑。

二、技术选型

核心方案

使用 File Viewer 开源前端组件，在浏览器端直接解析和渲染 .xmind 文件。

方案优势

无需额外的后端服务
数据在浏览器本地处理，保护隐私
部署简单，与 Caddy 配合良好

三、CDN 加载原理说明

资源加载流程

使用 CDN 链接 https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js 时：

浏览器解析 <script> 标签后，直接向 unpkg.com 服务器发起请求
CDN 服务器将 JS 文件内容传回浏览器
浏览器在本地执行该脚本

该模式的优势

云服务器无需承担脚本文件的流量和带宽消耗
公共 CDN 具有全球节点，加载速度更快
浏览器可缓存文件，重复访问速度提升
Caddy 无需为此进行任何特殊配置

四、基础部署方式

方式一：HTML 标签嵌入

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>XMind 在线预览</title>
</head>
<body>
    <flyfish-file-viewer 
        src="/path/to/your-file.xmind" 
        theme="light" 
        toolbar-position="bottom-right" 
        style="display:block; height:720px; width:100%;">
    </flyfish-file-viewer>

    <script src="https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js">
    </script>
</body>
</html>

方式二：mountViewer 方法（更灵活）

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>XMind 在线预览</title>
</head>
<body>
    <div id="viewer-container" style="height:720px; width:100%;"></div>

    <script src="https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js">
    </script>
    <script>
        window.onload = function() {
            FlyfishFileViewerWebFull.mountViewer(
                document.getElementById('viewer-container'), {
                    url: '/path/to/your-file.xmind',
                    options: {
                        theme: 'light'
                    }
                }
            );
        };
    </script>
</body>
</html>

五、URL 参数动态加载实现

需求说明

期望通过 https://zmind.zhaopeng.site/?file=your-file.xmind 形式的参数直接访问不同文件。

实现方案

方案一：通过 URL 参数指定文件名

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>XMind 在线预览</title>
</head>
<body>
    <flyfish-file-viewer 
        id="viewer"
        src="" 
        theme="light" 
        toolbar-position="bottom-right" 
        style="display:block; height:720px; width:100%;">
    </flyfish-file-viewer>

    <script src="https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js">
    </script>
    <script>
        const urlParams = new URLSearchParams(window.location.search);
        const fileName = urlParams.get('file'); 
        const viewer = document.getElementById('viewer');

        if (fileName) {
            viewer.setAttribute('src', fileName);
        } else {
            viewer.setAttribute('src', 'default.xmind'); 
        }
    </script>
</body>
</html>

方案二：mountViewer 方法动态加载

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>XMind 在线预览</title>
</head>
<body>
    <div id="viewer-container" style="height:720px; width:100%;"></div>

    <script src="https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js">
    </script>
    <script>
        const urlParams = new URLSearchParams(window.location.search);
        const fileName = urlParams.get('file') || 'default.xmind';

        window.onload = function() {
            FlyfishFileViewerWebFull.mountViewer(
                document.getElementById('viewer-container'), {
                    url: fileName,
                    options: {
                        theme: 'light'
                    }
                }
            );
        };
    </script>
</body>
</html>

六、页面全屏显示优化

问题描述

使用 mountViewer 方式时，预览区域未占满浏览器窗口。

原因分析

容器高度被固定为 720px，未随视口大小变化。

解决方案

方法一：使用 100vh

<div id="viewer-container" style="height:100vh; width:100%;"></div>

方法二：CSS 重置（推荐）

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>XMind 在线预览</title>
    <style>
        body {
            margin: 0;
            padding: 0;
            overflow: hidden;
            height: 100vh;
        }
        #viewer-container {
            width: 100%;
            height: 100%;
        }
    </style>
</head>
<body>
    <div id="viewer-container"></div>

    <script src="https://unpkg.com/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js">
    </script>
    <script>
        const urlParams = new URLSearchParams(window.location.search);
        const fileName = urlParams.get('file') || 'default.xmind';

        window.onload = function() {
            FlyfishFileViewerWebFull.mountViewer(
                document.getElementById('viewer-container'), {
                    url: fileName,
                    options: {
                        theme: 'light'
                    }
                }
            );
        };
    </script>
</body>
</html>

缩放模式调整

如内容仍居中且留白较多，可通过 fit 参数调整显示模式：

window.onload = function() {
    FlyfishFileViewerWebFull.mountViewer(
        document.getElementById('viewer-container'), {
            url: fileName,
            options: {
                theme: 'light',
                fit: 'width'  // 可选值：auto, width, height, cover, contain
            }
        }
    );
};

七、Caddy 服务器配置要点

基本要求

仅需提供静态文件服务
无需配置反向代理
确保 .xmind 文件路径可通过 file_server 指令访问

文件存放说明

HTML 页面和 .xmind 文件需放在同一目录，或根据实际路径调整 src 属性
使用 URL 参数方式时，文件名作为参数传递，需确保文件存在于服务器对应路径

八、安全注意事项

动态加载文件时，应限制可访问的目录范围
避免用户通过参数遍历服务器敏感文件
建议对文件路径进行校验，仅允许访问特定文件夹内的文件

caddy实现网页查看xmind文件