FlatNas 功能使用手册

仪表盘与布局

• 网格布局：自由拖拽，支持多尺寸组件。
• 分组管理：创建分组，分类管理应用与书签。
• 响应式设计：桌面与移动端自适应。
• 编辑模式：所见即所得，快速添加/删除/调整。

内置小组件

• 书签组件：支持自定义图标，首次启动自动填充常用站点。
• 时钟与天气：实时显示时间与当地天气。
• 待办事项：简易任务管理。
• RSS 订阅：获取订阅源最新内容。
• 热搜榜单：聚合热点信息。
• 计算器与音乐播放器：便捷工具与本地音乐播放。

个性化定制

• 图标管理：上传图片，支持 Hex 颜色。
• 背景设置：自定义壁纸。
• 分组卡片背景：统一图片/模糊/遮罩风格。
• 访客统计：页脚显示访问量与在线时长。
• 数据安全：本地存储配置，密码访问保护。
• CGI 扩展与更新提醒：支持脚本扩展与版本检测。

v1.0.28 dev 更新提示

• 更新前请在设置中导出配置（JSON），以便回滚。

v1.0.28 dev 新增/优化

• 添加容器的卡片管理。
• 侧边栏添加快捷分组。
• 优化手机端在侧边栏的展现。
• 修复侧边栏默认公开的问题。
• 优化天气状态位置。
• 优化快捷分组的拖动逻辑。
• 优化自动添加容器管理卡片的展现逻辑。

v1.0.24 新增/优化

• 日历组件视图精简与当天视图布局重写。
• 节日显示优先级优化与命名统一。
• 尺寸调整持久化修复与测试环境修复。
• 版本号更新为 v1.0.24。

获取最新更新内容

• 本文档的“近期更新”会随 README 同步，刷新页面即可看到最新变更。
• FlatNas 内置版本检测：在设置面板点击“检查更新”，可获取最新 Release 信息与 Docker 更新提示。
• 如使用 Docker，建议关注镜像 qdnas/flatnas 的最新标签。

获取源码与镜像

• GitHub：https://github.com/Garry-QD/FlatNas
• Gitee：https://gitee.com/gjx0808/FlatNas
• Docker Hub：https://hub.docker.com/r/qdnas/flatnas

加入交流QQ群

• 群号：613835409
• 加入方式：在 QQ 客户端中搜索群号 613835409；加群时请备注 “FlatNas”。

功能描述

• 多维度识别：客户端 IP、访问域名、网络延迟。
• 自动路由：内网优先使用 LanUrl，公网用外网地址。
• 无感切换：同一图标自动跳转最佳地址。

使用指南

• 在编辑窗口填写外网链接与内网链接。
• 典型场景：家庭 NAS、开发调试优先使用本地端口。

注意事项

• 反向代理需透传真实 IP（示例：设置 X-Forwarded-For）。
• 未配置内网地址时自动回退外网地址。

目录说明

• src：前端 Vue 源码。
• server：后端 Express 服务，含 data、music、cgi-bin、server.js。
• public：静态资源。
• dist：构建产物。

本地开发

• 克隆并安装依赖：git clone、npm install。
• 启动：npm start（前端与后端同时启动）。
• 地址：前端 http://localhost:5173，后端 http://localhost:3000。

Windows 注意

• PowerShell 执行策略问题可改用 cmd，或分别启动后端与前端。

部署构建

• 构建前端：npm run build（产物在 dist）。
• 运行生产服务：npm run server，通过 http://localhost:3000 访问。

构建镜像

docker build -t flatnas .

运行容器

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/server/data:/app/server/data \
  -v $(pwd)/server/music:/app/server/music \
  -v $(pwd)/server/PC:/app/server/PC \
  -v $(pwd)/server/APP:/app/server/APP \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name flatnas \
  qdnas/flatnas

注意: 建议挂载 data、music、PC 和 APP 目录，以确保配置数据、媒体文件和自定义壁纸在容器重启后不会丢失。若需要使用 Docker 管理功能，必须挂载 /var/run/docker.sock。

docker-compose 示例

version: '3.8'

services:
  flatnas:
    image: qdnas/flatnas:latest
    container_name: flatnas
    restart: unless-stopped
    ports:
      - '23000:3000'
    volumes:
      - ./data:/app/server/data #指定路径下新建data
      - ./music:/app/server/music #映射播放器路径
      - ./PC:/app/server/PC #映射PC端壁纸路径
      - ./APP:/app/server/APP #映射移动端壁纸路径
      - /var/run/docker.sock:/var/run/docker.sock #映射Docker Socket

快速安装（推荐）

无需手动下载代码，直接运行以下命令即可：

wget -O deploy.sh https://raw.githubusercontent.com/Garry-QD/FlatNas/main/deploy.sh && sudo bash deploy.sh install

手动安装

git clone https://github.com/Garry-QD/FlatNas.git
cd FlatNas
chmod +x deploy.sh
sudo ./deploy.sh install

关键路径

• 默认密码：admin，登录后请及时修改。
• 数据文件：server/data/data.json。
• 音乐文件：server/music（支持 MP3）。
• CGI 脚本：server/cgi-bin。

协议与声明

• 本项目采用 GNU AGPLv3 开源协议。
• 如进行二次开发与部署，请遵循协议要求。

创建与删除分组

排序与层级

支持拖拽排序功能。在编辑模式下，长按分组名称即可上下拖动调整顺序。

权限设置

您可以为特定分组设置访问权限：

• 公开：所有访客可见。
• 私有：仅登录管理员可见。
• 密码保护：访问时需输入独立密码。

分组设置详情

点击分组标题旁的设置按钮，可进入详细配置界面：

• 分组标题： 自定义分组名称。
• 公开此分组： 控制分组内容的可见性，开启后未登录用户也可访问。
• 自动隐藏标题： 开启后，分组标题仅在鼠标悬停时显示。
• 布局与间距：
  • 卡片布局： 可选择“垂直”或“水平”排列卡片。
  • 卡片间距： 调整卡片之间的距离。
  • 卡片大小： 调整卡片的整体尺寸。
  • 图标大小： 调整卡片内图标的尺寸。
• 卡片样式：
  • 卡片外观： 可设置背景色/字体颜色、背景图、透明度及显示状态。
  • 卡片背景图： 上传或选择卡片背景图片。
  • 圆角半径： 调整卡片的圆角大小。
  • 遮罩浓度： 调整背景图的遮罩透明度。
  • 图标形状： 可选择图标的显示形状，如“圆角矩形”。
• 恢复默认设置： 将当前分组设置恢复到系统默认状态。
• 删除此分组： 彻底删除该分组及其包含的所有项目。

新增项目

点击“新增项目”按钮，将弹出配置窗口，您可以详细设置新项目的各项属性：

• 公开显示： 开启后，该项目对所有访客可见。
• 标题： 项目的显示名称，支持自定义标题颜色。
• 外网链接： 项目的外部访问 URL，必填项。
• 内网链接： 可选，当在内网环境访问时，会优先使用此链接。
• 图标样式：
  • 图片： 支持上传本地图片或填写图片 URL，可调整缩放比例，并支持自动适配或抓取图标。
  • Emoji： 可选择系统内置的 Emoji 作为图标。
• 卡片背景： 可选，支持设置背景图（上传或 URL），并可配置模糊和遮罩效果。

分类与标签

为项目添加 Tags（标签）可实现快速筛选。例如标记为 #影视 #办公，在搜索栏输入标签即可快速定位。

编辑项目

在项目卡片上点击“编辑”或右键选择“修改项目”，进入编辑窗口：

• 标题与颜色： 修改项目名称并设置标题颜色。
• 外网/内网链接： 更新链接地址。内外网同时设置时，在局域网内优先使用内网链接。
• 图标管理： 支持图片/Emoji；提供 自动适配图标 与 自动抓取图标；可填写图片 URL 或上传并裁剪，配合 缩放 滑条调整大小。
• 卡片背景： 可设置背景图（URL 或上传），并支持模糊与遮罩效果。
• 保存修改： 点击“保存修改”应用更新；“取消”放弃当前变更。

项目常用操作

• 移动至分组： 将项目快速移动到其他分组以便分类管理。
• 置顶/排序： 拖拽调整项目顺序，或将重要项目置顶。
• 复制项目： 以当前项目为模板创建副本，便于批量添加相似服务。
• 删除项目： 从当前分组移除该项目，删除前请确认。
• 搜索与筛选： 通过名称或标签快速定位项目。

链接优先策略

当同时设置外网与内网链接时：

• 内网优先： 局域网访问时优先跳转到内网链接。
• 外网回退： 在无法访问内网或外部网络环境下，自动使用外网链接。

输入校验与建议

• URL 格式： 需为有效的 http/https 链接，推荐显式填写端口。
• 图标与背景： 建议使用清晰的 PNG/SVG/JPG 资源以获得更佳显示效果。
• 命名规范： 项目标题保持简洁（建议不超过 12 个字）。

编辑入口

在项目卡片上点击“编辑”或右键选择“修改项目”进入卡片编辑窗口。

样式配置

在卡片设置中，您可以调整：

• 背景颜色 / 透明度
• 圆角大小 (0px - 20px)
• 图标尺寸 (小/中/大)
• 点击特效 (波纹/缩放)

基础信息

• 标题： 卡片上显示的名称，支持设置标题颜色。
• 描述： 鼠标悬停时显示的提示文本（可选）。
• 公开显示： 控制该项目是否对所有访客可见。

链接配置

• 外网链接： 访问互联网时使用的 URL（必填）。
• 内网链接： 在局域网环境优先跳转的 URL（可选）。
• 打开方式： 支持在新标签页或当前页面打开。

图标设置

• 样式选择： 选择 图片 或 Emoji 作为卡片图标。
• 自动适配图标： 根据卡片背景与尺寸自动优化图标显示。
• 自动抓取图标： 从链接站点智能获取 favicon 作为图标。
• 图片 URL： 直接填写图标图片的网络地址。
• 本地上传/裁剪： 上传本地图标并支持裁剪，配合 缩放 滑条调节大小。
• 图标形状： 可选圆角矩形、圆形等样式以统一风格。

背景与外观

• 背景色/文字色： 独立设置卡片背景与文字颜色。
• 背景图： 支持 URL 或 本地上传，并可应用模糊与遮罩效果。
• 透明度： 调整背景透明度以适配不同主题。
• 圆角半径： 统一卡片的圆角风格。
• 阴影与悬停： 配置卡片阴影与悬停高亮效果。

布局与排序

• 卡片大小： 统一控制卡片的整体尺寸。
• 卡片间距： 在分组设置中调整该分组内卡片的间距。
• 置顶/排序： 支持将重要卡片置顶或调整排序位置。
• 标签： 为卡片添加标签以便搜索与筛选。

交互行为

• 点击特效： 可选波纹或缩放反馈。
• 悬停效果： 高亮、阴影或透明度变化以提升可用性。

保存与回滚

• 保存修改： 点击“保存修改”应用当前设置。
• 取消： 放弃当前编辑并恢复到进入编辑前的状态。
• 历史记录回滚： 在系统设置的历史记录中可回滚到最近的修改版本。

进入/退出

点击页面右下角的 悬浮按钮即可进入编辑模式。再次点击或按 Esc 键退出。

批量操作

按住 Ctrl (Mac 为 Command) 点击卡片可进行多选，支持批量移动、批量删除或修改颜色。

拖动组件调整位置

• 进入编辑模式后，按住组件卡片即可拖动到目标位置。
• 支持网格吸附与自动对齐，松开后卡片将自动贴合最近网格。
• 拖动过程中页面支持自动滚动，便于跨区域移动。

编辑组件的展现尺寸

• 点击组件右下角的设置按钮，打开“调整尺寸”网格选择器。
• 通过选择 行 × 列 规格（如 1×3、2×2 等）设置组件的占位大小。
• 尺寸变更后会即时预览，保存后生效。

卡片（图标）换组拖动

• 按住卡片将其拖拽到目标分组区域，分组边框会高亮提示可放置。
• 松开即完成换组，卡片将遵循目标分组的布局与样式。
• 支持批量选择后整体拖动到新分组。

分组位置调整

• 在分组标题区域按住拖动手柄或标题栏，拖拽分组至新位置。
• 支持上下排序与跨行移动，松开后自动对齐。
• 分组排序改变不会影响组内项目的相对顺序。

版本控制

系统自动保存最近 10 次修改记录。如误操作，可在 "设置 > 历史记录" 中一键回滚。

全局样式

支持 浅色/深色 主题自动切换。您也可以自定义背景壁纸（支持图片/视频）。

数据备份

在 "高级设置" 中点击 "导出配置" 即可下载备份文件。恢复时直接上传该文件即可覆盖当前设置。

基础信息

• 网站标题： 设置页面顶部显示的站点名称。
• 背景图片： 支持上传或选择图片，提供“清除背景”和“管理壁纸库”。
• 主题模式： 浅色/深色/自动随系统。
• 导航栏： 显示/隐藏顶部导航，可设置透明度与固定方式。

布局与排版

• 顶部栏布局： 在“标准布局”和“反转布局”之间切换。
• 标题大小： 通过滑条调节页面主标题字号。
• 标题颜色： 使用颜色选择器设置标题颜色，支持“重置”为默认。
• 分组垂直间距： 通过滑条调整分组之间的上下间距。

页脚设置

• 显示访客统计： 开启后在页脚展示访客统计信息。
• 页脚高度 (px)： 设置页脚高度，0 为自适应。
• 页脚内容宽度 (px)： 设置内容最大宽度，默认 1280。
• 页脚距离底部 (px)： 调整页脚的垂直位置。
• 页脚字体大小 (px)： 设置页脚文字大小，默认 12。
• 自定义页脚内容 (HTML)： 可输入备案号等信息，支持 HTML 标签。

通用开关与操作

• 公开： 允许未登录访客查看该组件。
• 启用： 打开/关闭组件在桌面的显示。
• 手机： 控制组件在移动端是否显示。
• 自动： 仅对支持的组件提供自动行为（如随机音乐的自动播放）。
• 恢复默认组件： 一键恢复到系统默认的组件配置。

组件清单与功能

天气服务设置

• 天气源选择： 默认 Wttr.in，可切换为 高德地图 (AMap)。
• 自定义天气源 URL： 输入自定义接口地址，返回 { data: { temp, text, city, humidity, today: { min, max } } } 的 JSON 格式。

组件总开关

• 公开： 控制 RSS 阅读器组件是否对访客可见。
• 启用： 打开/关闭桌面上的 RSS 阅读器组件显示。
• 云端同步： 顶部显示“云端同步已开启/关闭”的状态提示。

新增订阅源

• 标题： 订阅源名称，例如“少数派”。
• RSS 地址： 输入源的订阅 URL（必须为有效的 http/https）。
• 分类： 选择或输入分类名称，将订阅源归类管理。
• 标签： 多标签支持（逗号分隔），便于筛选。
• 启用/公开： 控制该订阅源是否参与聚合与是否对访客可见。
• 保存/取消： 完成配置后保存，或取消返回列表。

订阅源列表与操作

• 列表视图： 显示所有订阅源名称与 RSS 链接，以及“已启用/公开”状态。
• 管理分类： 进入分类管理页面，对分类进行新增/重命名/删除。
• 编辑： 修改已有订阅源的标题、地址、分类、标签与状态。
• 删除： 从列表移除订阅源（不可恢复）。
• 移动到分类： 将订阅源快速分配到指定分类。
• 搜索与筛选： 通过标题/标签/分类快速定位订阅源。

分类管理

• 添加新分类： 输入分类名称并添加；空状态下显示“暂无分类”。
• 返回订阅列表： 一键返回主列表页面继续管理订阅。
• 分类排序： 支持对分类进行排序以优化展示。

显示与刷新

• 阅读模式： 支持摘要/全文展示，显示未读数提示。
• 更新频率： 设置拉取间隔与最大缓存条目数，保证性能与实时性平衡。
• 手动刷新： 在组件中可手动触发更新。

异常处理与同步

• 失败重试： 订阅失败时进行自动重试与源可用性提示。
• 云端同步： 在开启云端同步后，源配置与阅读状态可在多设备间保持一致。

搜索栏显示

• 显示搜索栏： 开启后在桌面顶部显示搜索输入框。
• 记住上次选择： 勾选后，系统在下次打开时仍使用上次选定的搜索引擎。
• 快捷键： 按 / 快速聚焦搜索框。

引擎列表与管理

• 排序： 通过拖动引擎左侧手柄调整优先级。
• 设为默认： 点击单选按钮设置为默认引擎，当前默认会显示“当前默认”。
• URL 模板： 使用 {q} 作为查询词占位，例如：
  https://www.baidu.com/s?wd={q}
  https://www.google.com/search?q={q}
  https://cn.bing.com/search?q={q}
• 新增引擎： 输入名称与模板即可添加，系统会对查询词进行 URL 编码。
• 删除： 支持删除不需要的搜索引擎。

其他设置

• 快捷切换： 在顶部下拉中快速切换当前搜索源。
• 安全过滤： 可选开启安全搜索与区域偏好。

通用说明

• 可多开： 同一组件可创建多个实例并独立配置。
• 开关： 每个实例都支持“公开/手机/启用”独立控制。
• 删除： 支持单实例删除，不影响其他实例。

万能窗口

• 外网/默认地址： 组件的默认访问 URL。
• 内网地址： 在局域网环境下优先使用的 URL（内网优先）。
• 嵌入行为： 以窗口形式嵌入网页，少数站点可能因下载、验证码或跨域策略而无法正常嵌入。
• 状态开关： 公开、手机端、启用可分别控制。

倒计时

• 标题： 为倒计时设置描述性标题。
• 目标时间： 选择日期与时间，倒计时将实时显示剩余时间。
• 实例控制： 支持公开/手机/启用独立开关与删除。

宿主机状态组件

• 组件总开关： 顶部开关控制宿主机状态组件的显示。
• 公开访问： 允许访客查看宿主机状态。
• 手机端显示： 控制移动端是否显示。
• 使用模拟数据： 在无数据源或调试时使用内置示例数据。
• 测试连接： 点击进行探针/API 的连通性测试。
• 展示信息： 系统版本、内核、运行时长、设备标识，以及 CPU 温度/占用、RAM 使用、磁盘占用、网络接口速率 等。

Docker 组件列表

• 组件开关： 公开、手机端显示、支持启动/停止/重启、使用模拟数据。
• 内网主机： 配置宿主机地址（如 192.168.1.10），用于容器的内网访问与控制。
• 容器列表： 展示容器名称、镜像、Up 运行时长、暴露端口，以及 CPU/MEM 的实时占用。
• 打开方式： 每个容器支持 内网打开/外网打开，并可 添加外网地址。
• 添加卡片： 将容器以卡片形式添加到桌面，便于快速访问与观察。

容器卡片与操作菜单

• 卡片信息： 显示 CPU/MEM 叠层标识以及 NET/IO 速率指标。
• 右键菜单： 包含 内网访问、外网访问、停止容器、重启容器、编辑卡片、删除卡片 等操作。
• 操作权限： 启停/重启需在探针或后端启用控制权限，通常仅管理员可见与可用。

数据来源与权限控制

• 数据源配置： 可配置本地探针或后端 API 端点以获取宿主机与容器状态。
• 跨域与安全： 如采用远端 API，需确保跨域策略与认证已正确配置。
• 管理员可见： 容器控制相关操作默认仅管理员账号可使用。

备份与恢复

• 导出配置： 将当前所有设置导出为 JSON 文件，便于备份与迁移。
• 导入配置： 上传备份文件以恢复配置，支持覆盖当前设置。
• 设为默认模板： 将当前配置保存为系统默认模板，供初始化或重置时使用。
• 恢复初始化： 将系统恢复到初始状态，谨慎使用（会清空现有配置）。

系统模式

• 当前模式显示： 显示“单用户模式”或“多用户模式”。
• 切换为多用户模式： 启用登录与权限管理，适合多人使用场景。
• 默认管理员： 首次启用多用户模式会提供默认管理员账号与密码（通常为 admin/admin），请立即修改。
• 保存为版本： 为当前配置输入版本名称并保存，形成可回滚的配置快照（保存位置示例：data/config_versions）。

密码与登录

• 修改密码： 输入新密码并点击“修改”，立即生效。
• 退出登录： 立即退出当前管理员会话。
• 公开/私有策略： 私有分组与高级设置仅登录后可见，未登录状态仅显示公开内容。

安全建议

• 首次登录后修改默认密码： 防止未经授权的访问。
• 定期备份： 建议开启版本化保存，出现误操作可快速回滚。
• 忘记密码： 请参考“使用说明 > FAQ”，根据部署方式在服务器端重置认证配置。

天气服务设置

在组件设置中，您可以对天气服务进行详细配置：

• 天气源选择： 默认为 Wttr.in，也支持切换为高德地图 (AMap) 以获得更精准的国内天气数据。
• 自定义源： 支持输入自定义 API URL，需返回特定 JSON 格式数据：{ data: { temp, text, city, humidity, today: { min, max } } }。

快捷键汇总

常见问题 (FAQ)