FlatNas 功能使用手册

整体界面

左侧为可收起的侧边栏（书签 / 分组双视图），顶部为标题与搜索栏，主体为可自由拖拽的组件网格。下方为一张实拍总览：

仪表盘与布局

• 网格布局：自由拖拽，支持半格等多尺寸组件，自动吸附对齐。
• 分组管理：创建多个分组，分类管理应用与书签，并支持拖拽排序。
• 响应式设计：桌面 / 平板 / 手机分端布局，可单独为每个设备调整位置与尺寸。
• WEB 端展现方式：支持“一栏页 / 按组分页”，并可禁止翻页。
• 编辑模式：所见即所得，右键卡片即可编辑、复制、移动、删除。

内置小组件（实拍）

FlatNas 内置了丰富的实用小组件，以下为多个组件的真实运行截图：

时钟

天气

日历（含农历/节气/节假日）

待办事项

倒计时

正计时

IP / 网络信息

文件传输助手

书签卡片

• 文件传输助手：支持文本 / 文件 / 图片互传，分片上传、断点续传、大文件上传，并内置图片视图自动归类预览，支持缩略图重新生成。
• 书签组件：快速访问常用网站，支持自定义图标，首次启动自动填充常用站点。
• 时钟与天气：实时显示时间、日期与当地天气，支持多数据源。
• 日历：内置农历、节气、节假日与纪念日，支持多种视图。
• 待办 / 备忘录：任务清单与随手记录，支持多端实时同步。
• RSS 订阅：内置阅读器，订阅源管理与云端同步。
• 热搜榜单：聚合微博、新闻等即时热点。
• 音乐播放器：内置 MiniPlayer，播放服务器本地音乐；并支持“道理鱼”音乐组件。
• 计算器 / 聚合搜索 / 每日一言 / 侧边栏 等实用工具。

个性化定制

• 图标管理：内置图标库，支持上传自定义图片，并全面支持 Hex 颜色代码（如 #ffffff）自定义图标背景色。
• 背景设置：支持自定义壁纸、纯色背景、壁纸库与轮播。
• 白昼模式：按时间段自动调整背景遮罩（白天 6:00–18:00，夜间 18:00–6:00）。
• 环境天气效果：雨天自动开启背景雨效。
• 分组卡片背景：在分组设置中统一配置该组所有卡片的背景（图片、模糊、遮罩）。
• 访客统计：底部页脚显示网站总访问量、今日访问量及当前在线时长。
• 数据安全：本地存储配置，密码访问保护，支持配置版本回滚。
• 更新提醒：内置版本检测，自动查询 Gitee 仓库最新标签（gitee.com/gjx0808/FlatNas）并在设置面板提示；Docker 部署时同时检测镜像更新。

架构升级

• 后端由 Node/Express 重构为 Go (Gin)，资源占用更低、单文件即可部署。
• 前端使用 Vue 3 + TypeScript + Pinia，组件按需加载。
• 无数据库，所有数据以 JSON 文件存储，迁移与备份更方便。

新增 / 优化

• 全站多语言：简体中文 / 繁體中文 / English / 日本語 / Deutsch / Français / Español。
• 网络判定升级：域名白名单 + 延迟判定、预设规则（Tailscale / ZeroTier / FRP / Cloudflare Tunnel / ngrok）、强制网络模式、延迟阈值、白名单延迟模式。
• 前端新增网络状态指示器：显示在线 / HTTP 同步 / 游客 / 离线等状态与待同步条数。
• 外观布局增强：顶栏标准 / 反转布局、WEB 端按组分页、鼠标悬停效果（缩放 / 上浮 / 发光）、组件区整区尺寸、自定义页脚 HTML。
• 新增 白昼模式 与 环境天气效果（雨天背景雨效）。
• 新增侧边栏快捷分组，优化手机端侧边栏展现与拖动逻辑。
• 多端同步增强：WebSocket 广播 + HTTP 轮询降级 + 离线队列 + IndexedDB 缓存；备忘录加入冲突解决机制。
• Docker 管理增强：服务总开关、宿主机状态组件、容器管理、镜像自动升级（每 2 小时）、旧镜像清理、磁盘保护、模拟数据。
• 开放中心：自定义 CSS / JS、浏览器助手握手、Webhook / STUN 穿透、天气源多源接入、道理鱼音乐、授权密钥。
• 新增高德天气组件（支持多开）、倒计时、正计时组件。
• 图标智能匹配与预加载、图标缓存，提升首屏与书签图标抓取体验。
• 新增配置版本管理：保存 / 恢复 / 删除配置快照，误操作可快速回滚。

本地开发与构建

• 本地开发：
  • 克隆并安装依赖：git clone、npm install（在 frontend 目录）。
  • 启动：npm start（前端 Vite 与后端同时启动）。
  • 地址：前端 http://localhost:23000，后端 API http://localhost:3000。
• 部署构建：
  • 构建前端：npm run build（产物输出到后端静态目录）。
  • 启动后端服务后，通过 http://<服务器IP>:3000 访问。

FPK 安装

飞牛私有云 (fnOS)： 飞牛私有云 fnOS 应用中心搜索 FlatNas 即可一键安装。

Docker 部署

docker build -t flatnas .

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

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 #映射背景路径
      - ./APP:/app/server/APP #映射移动端背景路径
      - ./doc:/app/server/doc #映射文件传输助手路径
      - /var/run/docker.sock:/var/run/docker.sock #映射Docker Socket

一键部署 (Debian/Ubuntu)

适用于 Debian/Ubuntu，无需 Docker，脚本会自动下载最新 Release 并完成部署。

wget -O deploy_debian.sh https://raw.githubusercontent.com/Garry-QD/FlatNas/main/deploy_debian.sh
chmod +x deploy_debian.sh
sudo ./deploy_debian.sh

wget -O manage.sh https://raw.githubusercontent.com/Garry-QD/FlatNas/main/manage.sh
chmod +x manage.sh
sudo ./manage.sh

sudo ./manage.sh

关键路径

• 默认密码：admin，登录后请及时修改。
• 单用户数据：server/data/data.json；多用户数据：server/data/users/{用户名}.json。
• 系统配置：server/data/system.json（认证模式、Docker 开关等）。
• 配置版本备份：server/data/config_versions。
• 音乐文件：server/music（支持 MP3）。
• 背景图片：server/PC（PC 端）、server/APP（移动端）。
• 文件传输助手：server/doc/transfer。
• 图标缓存：server/data/icon-cache。
• Docker Socket：/var/run/docker.sock（需挂载）。

进入 / 退出

点击页面右下角或顶部的 编辑按钮即可进入编辑模式，再次点击退出。未登录时点击会弹出登录窗口。

拖动组件和项目说明

• 进入编辑模式后，按住组件卡片即可拖动到目标位置。
• 支持网格吸附与自动对齐，松开后卡片将自动贴合最近网格。
• 拖动过程中页面支持自动滚动，便于跨区域移动。
• 按住卡片将其拖拽到目标分组区域，分组边框会高亮提示可放置。
• 松开即完成换组，卡片将遵循目标分组的布局与样式。

实时同步

• 双通道通信：优先 WebSocket 广播，网络受限时自动降级为 HTTP 轮询。
• 离线队列：断网期间的修改进入本地队列，恢复后自动补发。
• 本地缓存：基于 IndexedDB / localStorage 缓存，首屏秒开。
• 智能冲突处理：仅布局/分组/配置结构变动时提示冲突，纯内容变更（如备忘录文字）自动同步。
• 网络状态指示：页面角标显示“在线 / HTTP 同步 / 游客 / 离线”，并提示待同步条数。

导航与布局

网络与同步

组件与个性化

运维与账户

功能概述

壁纸库提供强大的背景管理功能，支持双端独立设置、自动轮播以及第三方 API 接入。

核心组件清单

FlatNas 目前提供以下内置组件（单开 / 可多开）：

提示：标注“可多开”的组件（内嵌页面、倒计时、正计时、高德天气）可创建多个实例并独立配置，详见 多开组件 章节；Docker 管理为专属组件，只能存在一个实例。

高级配置：RSS 订阅管理

RSS 组件支持更深层次的个性化配置，确保信息获取的及时与同步。

• 云端同步：开启后支持多端订阅源同步。
• 分类管理：对不同的订阅源进行分类整理。
• 快速新增 / 批量导入：支持每行一个 URL，或“标题 URL / 标题,URL / 标题 | URL”格式批量导入，并自动抓取远端标题。

订阅源实例推荐

高级配置：搜索引擎设置

自定义您的桌面搜索框，支持多引擎切换与优先级调整。

• 排序与优先级：拖动引擎左侧的三横线图标可调整显示顺序。
• 默认设置：一键设置百度、谷歌或 Bing 为您的默认搜索引擎。
• URL 模板：支持自定义搜索引擎 URL 模板（例如：.../s?wd={q}）。
• 记住上次选择：开启后将自动保留您最近一次使用的引擎。

万能窗口（内嵌页面）

万能窗口基于 iframe 开发，可以在当前页直接打开其他网站。需要注意的是，部分网站配置了拒绝 iframe 嵌入的策略，这类网站需要安装并启用我们的浏览器插件后才能正常显示。

万能窗口自带 3 个便捷按钮，支持 刷新、视角切换（手机/PC 模式）以及 新窗口打开，方便您快速操作嵌入的网页。

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

倒计时 / 正计时

• 标题：为计时器设置描述性标题。
• 目标时间 / 起始时间：倒计时面向目标日期实时显示剩余时间；正计时自起始时间累计。
• 实例控制：支持公开 / 手机 / 启用独立开关与删除。

宿主机状态组件

• 组件总开关：顶部开关控制宿主机状态组件的显示。
• 公开访问 / 手机端显示：分别控制访客与移动端的可见性。
• 使用模拟数据：在无数据源或调试时使用内置示例数据。
• 展示信息：系统版本、内核、运行时长、设备标识，以及 CPU 温度 / 占用、RAM 使用、磁盘占用、网络接口速率 等。

容器管理

• 组件开关：公开、手机端显示、容器管理组件、使用模拟数据。
• 内网主机：配置宿主机地址（如 192.168.1.10），用于容器的内网访问与控制。
• 镜像自动升级：每 2 小时对比镜像 ID，发现新版本自动重建容器；关闭时后台不做任何镜像拉取。
• 旧镜像清理：升级完成后自动清理旧镜像，默认每个镜像名保留 2 个版本（可配置 1–20）。
• 磁盘保护：当 Docker 所在磁盘可用空间低于阈值时跳过本轮升级，默认阈值 5GB（可配置）。

容器卡片与操作菜单

• 卡片信息：显示容器名称、镜像、Up 运行时长、暴露端口，以及 CPU/MEM 实时占用。
• 打开方式：每个容器支持 内网打开/外网打开，并可添加外网地址。
• 右键菜单：包含内网访问、外网访问、停止容器、重启容器、编辑卡片、删除卡片等操作。
• 添加卡片：将容器以卡片形式添加到桌面，便于快速访问与观察。
• 权限：启停 / 重启等操作默认仅管理员账号可用，需在后端启用控制权限。

配置版本管理

• 保存版本：为当前配置输入版本备注并保存，形成可回滚的快照（保存位置：server/data/config_versions）。
• 恢复 / 删除：随时恢复某个版本，或删除不再需要的版本。
• 密码与登录：修改密码、退出登录；私有分组与高级设置仅登录后可见。

安全建议

• 首次登录后修改默认密码：防止未经授权的访问。
• 定期备份：建议使用配置版本保存，出现误操作可快速回滚。
• 忘记密码：在数据文件中搜索 password 字段。
  • 您会看到一串乱码（如 "$2a$14$..."），这是加密后的密码。
  • 将其直接修改为您想要的明文密码，例如："password": "123456"。
  • 重启服务器：保存文件并重新启动服务器。
  • 登录：使用新密码 123456 登录。系统在首次登录成功后会自动将其加密存储。

数据备份说明

在“账户管理”中点击“导出配置”即可下载备份文件。恢复时直接上传该文件即可覆盖当前设置。

☁️ 天气服务设置

配置您的桌面天气组件数据来源，支持多种国内外主流天气源及自定义接口。

• 天气源选择：内置 Wttr.in（默认）、高德地图 (AMap) 以及 和风天气 (QWeather)。
• 鉴权配置：按所选数据源填写 API Key / JWT / Project ID / Key ID / Private Key 等参数，并支持一键“测试连接”。
• 自定义天气源 URL：支持输入自定义接口地址，需返回指定的 JSON 格式数据。

🔗 Webhook 设置（内测中）

支持通过 Webhook 接收外部事件触发，实现与第三方服务的联动自动化。

• Webhook 地址：系统提供唯一的 Webhook 接收地址，可用于 STUN 穿透等场景。
• 配置示例：系统给出请求头与请求体模板（如 {"stun":"success","ip":"#{ip}","port":"#{port}"}）。
• 最新状态：实时展示最近一次 Webhook 触发的状态与数据。

🛠️ 第三方接入

• API 接口：提供标准 RESTful API，支持第三方应用接入与数据交互。
• 自定义组件：支持以 HTML + CSS + JS 编写自定义组件，实现更多功能。

版本信息

• 当前版本：v1.2.6
• 技术栈：Vue 3 + TypeScript + Go (Gin)，无数据库（JSON 文件存储）。
• 内置版本检测：设置面板可查询 Gitee 最新标签版本并提示 Docker 镜像更新。

加入交流QQ群

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

开源协议

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

官方链接

• 官网：https://flatnas.top/
• 飞牛百科：http://qdnas.icu/
• 图标库主站：https://nasicon.top/
• 图标库二站：https://2.nasicon.top/
• 图标库三站：https://4.nasicon.top/
• Gitee：https://gitee.com/gjx0808/FlatNas
• GitHub：https://github.com/Garry-QD/FlatNas
• Docker Hub：https://hub.docker.com/r/qdnas/flatnas