qdnas/flatnas

By qdnas

•Updated 4 months ago

Image

Content management system

500K+

Overview Tags

qdnas/flatnas repository overview

⁠FlatNas

FlatNas 是一个轻量级、高度可定制的个人导航页与仪表盘系统。它基于 Vue 3 与 Go(Gin) 构建，旨在为 NAS 用户、极客和开发者提供一个优雅的浏览器起始页。交流QQ群:613835409

⁠✨ 功能概览

多端统一入口: 把常用网站、内网服务和工具聚合在同一仪表盘。
文件与媒体能力: 内置文件传输助手、音乐播放器和壁纸管理。
内外网智能切换: 自动识别网络环境并路由到最佳地址。
本地数据可控: 配置与数据存储在本地目录，迁移与备份更方便。
可视化组件生态: 内置多种组件，支持自定义 CSS/JS 深度扩展。
资源内存占用极低: NAS端占用100MB内存，访问端真实内存占用不到80兆。
支持docker管理: 内置docker管理组件，支持查看、启动、停止、重启docker容器、升级镜像等。

⁠🖥️ 仪表盘与布局

网格布局: 自由拖拽布局，支持不同尺寸的组件。
分组管理: 支持创建多个分组，分类管理应用和书签。
响应式设计: 完美适配桌面端和移动端访问。
编辑模式: 直观的所见即所得编辑体验，轻松添加、删除和重新排列组件。

⁠🧩 丰富的小组件

FlatNas 内置了多种实用的小组件，满足日常需求：

文件传输助手: 强大的跨设备传输工具。支持发送文本、文件与图片；支持断点续传、大文件上传；提供专属图片视图，自动归类并预览所有图片文件。
书签组件: 快速访问常用网站，支持自定义图标。首次启动时会自动填充常用的 10 个网站（如 GitHub, Bilibili 等）。
时钟与天气: 实时显示当前时间、日期及当地天气情况。
高德地图组件: 支持添加高德地图组件，显示当前位置及地图导航。
待办事项 (Todo): 简单的任务管理，随时记录灵感和待办。
RSS 订阅: 内置 RSS 阅读器，实时获取订阅源的最新内容。
热搜榜单: 集成微博热搜、新闻热榜等，不错过即时热点。
计算器: 随时可用的简易计算器。
音乐播放器: 内置 MiniPlayer，支持播放服务器端的本地音乐文件。
Docker管理: 内置docker管理组件，支持查看、启动、停止、重启docker容器、升级镜像等。
系统监控: 内置系统监控组件，支持查看CPU、内存、磁盘、网络等系统信息。
iframe组件: 支持嵌入外部网页，如视频、地图等。
自定义组件: 支持添加自定义 HTML 组件，实现更多功能。
道理鱼组件: 支持添加道理鱼音乐组件。

⁠🎨 个性化定制

FlatNas 提供了丰富的自定义选项，并自建了60000个图标的图标库，满足不同用户的需求：

自定义组件: 支持添加自定义 HTML 组件，实现更多功能。
自定义CSS: 支持添加自定义 CSS 样式，实现更多定制化效果。
自定义JS: 支持添加自定义 JS 脚本，实现更多功能。
自定义HTML: 支持添加自定义 HTML 代码，实现更多定制化效果。
天气组件: 支持添加天气组件，显示当前天气情况。
图标管理: 内置图标库，支持上传自定义图片，并全面支持 Hex 颜色代码 (如 #ffffff) 自定义图标背景色。
背景设置: 支持自定义壁纸。
分组卡片背景: 支持在分组设置中统一配置该组所有卡片的背景（图片、模糊、遮罩），实现风格统一的视觉效果。
访客统计: 底部页脚显示网站总访问量、今日访问量及当前在线时长（需在设置中开启）。
数据安全:
- 本地存储配置 (server/data/data.json)，数据完全掌握在自己手中。
- 简单的密码访问保护（默认密码：admin），保护隐私配置。
更新提醒: 内置版本检测功能，自动检查 GitHub 最新 Release 版本，并在设置面板提示 Docker 更新。

⁠🌐 代理配置

FlatNas 支持通过后端代理转发请求，以解决内网服务无法直接访问外网资源的问题，或实现简单的隐私保护。

⁠启用方法

设置环境变量 在 docker-compose.yml 或启动命令中添加 PROXY_URL 环境变量。

environment:
  - PROXY_URL=http://127.0.0.1:7890
  # 支持协议：http, https, socks5, socks5h
  # 格式：protocol://[user:pass@]host:port

前端开启 当环境变量配置正确后，在卡片编辑或万能窗口配置中，会显示“代理”开关。开启后，该组件的所有请求将通过 FlatNas 后端服务器代为转发。

⁠调试与排查

开关不显示：请检查后端日志，确认 PROXY_URL 格式正确且已生效。访问 /api/config/proxy-status 可查看当前代理可用状态。
请求失败：
- 检查 PROXY_URL 指向的代理服务器是否可达。
- 检查目标 URL 是否触发了 SSRF 防护规则（如禁止访问 localhost）。
- 查看后端日志 [Proxy Error] 获取详细错误信息。

⁠🌐 智能网络环境检测

FlatNas 后端集成了智能网络环境识别功能，能够根据用户的访问来源自动切换内外网访问策略，完美解决混合网络环境下的访问难题。

多维度识别: 结合 客户端 IP、访问域名 和 网络延迟 三个维度，精准判断用户当前所处的网络环境（局域网/互联网）。
自动路由: 当检测到用户处于局域网（LAN）时，系统会自动优先使用配置的 内网地址 (LanUrl)，实现高速直连；在公网环境则自动切换至 外网地址。
无感切换: 用户无需手动干预，无论是在家（内网）还是外出（外网），点击同一个图标即可自动跳转至最佳地址。

⁠📦 安装与部署

⁠1. 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

⁠Debian/Ubuntu 管理面板（管理脚本）

部署完成后，使用管理脚本进行常用运维操作（查看状态、修改端口、配置 HTTPS、查看日志、卸载）。

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

菜单功能说明：

查看服务状态：查看前后端端口、HTTPS 状态与服务运行情况
修改端口配置：修改前端端口与后端端口并自动重启服务
配置 HTTPS：写入证书并更新 Nginx 配置
查看实时日志：跟随服务日志
重启所有服务：重启 Nginx 与 FlatNas 服务
卸载服务：彻底卸载 FlatNas、配置与日志

⁠Debian/Ubuntu 卸载（命令行）

如果需要卸载，也可以直接运行管理脚本并选择“卸载服务”。

sudo ./debian/manage.sh

⁠2. 本地安装（Release 包）

适用于已能访问服务器的场景，上传 Release 包内容后直接运行。

从 GitHub Releases 下载 release.zip
上传到服务器并解压到任意目录（例如 /opt/flatnas）
进入解压目录并启动服务

cd /opt/flatnas
chmod +x flatnas-server
./flatnas-server

访问地址：http://<服务器IP>:3000

⁠3. Docker CLI 部署

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

⁠4. 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
      - ./doc:/app/server/doc
      - ./music:/app/server/music
      - ./PC:/app/server/PC
      - ./APP:/app/server/APP
      - /var/run/docker.sock:/var/run/docker.sock

⁠⚙️ 配置说明

默认密码: 系统初始密码为 admin，请登录后在设置中及时修改。
数据文件: 所有配置（布局、组件、书签等）均存储在 server/data/data.json 中。
音乐文件: 将 MP3 文件放入 server/music 目录，刷新页面后即可在播放器中看到。
Docker 自动升级镜像:
- 入口：设置 → Docker 管理 → 自动升级镜像(每2小时)。
- 关闭时：后台不会进行任何镜像拉取或版本对比。
- 开启时：每 2 小时对运行中的容器执行“拉取并对比镜像 ID”，发现新版本则自动重建容器。
- 镜像清理：升级完成后自动清理旧镜像，默认每个镜像名保留 2 个版本（可配置 1–20）。
- 磁盘保护：当 Docker 所在磁盘可用空间低于阈值时跳过本轮升级，默认阈值 5GB（可配置）。
- 监控指标：镜像数量、磁盘使用率、自动升级日志中的 pulls/updates/pruned/error 计数。
- 升级后验证：开启开关等待一个周期（或手动触发一次更新检测），确认日志中 pulls/updates 变化且镜像数量不持续增长。
- 灰度验证（建议）：准备 2 个环境分别开启/关闭该开关，各运行 24 小时，对比以下数据以确认“开关状态=后台行为”且无镜像堆积：
  - 服务器日志：筛选 [AutoUpdate] 与 [UpdateChecker] 关键字，统计 pulls/updates/pruned/error 次数与频率。
  - Docker 镜像数量：对比 24 小时前后 docker images -q | wc -l（Linux）或 docker images -q | Measure-Object -Line（PowerShell）。
  - Docker 根目录磁盘：对比 24 小时前后磁盘可用空间（或使用 docker info + 系统磁盘监控）。

⁠🎨 全局自定义 CSS

在设置 -> 自定义 CSS 中，您可以编写全局生效的 CSS 样式。

增强语法： FlatNas 支持以下自定义标签，自动转换为媒体查询，方便响应式适配：

<mobile>...</mobile>: 仅在移动端生效 (max-width: 768px)
<desktop>...</desktop>: 仅在桌面端生效 (min-width: 769px)
<dark>...</dark>: 仅在深色模式下生效
<light>...</light>: 仅在浅色模式下生效

示例:

/* 全局修改滚动条样式 */
::-webkit-scrollbar {
  width: 6px;
}

/* 仅在移动端隐藏侧边栏 */
<mobile>
.sidebar { display: none; }
</mobile>

⁠⚡ 全局自定义 JS

在设置 -> 自定义 JS 中，您可以注入 JavaScript 代码以实现高级交互或逻辑增强。 注意：启用此功能需要同意安全免责声明。

运行环境 (Runtime Context):

代码将在沙箱环境中运行，并提供 ctx 对象用于与系统交互。支持直接编写代码或导出生命周期钩子。

生命周期钩子 (推荐):

// @module
// 必须使用 export default 导出钩子对象
export default {
  /**
   * 初始化时调用
   * @param {object} ctx - 上下文对象
   */
  init(ctx) {
    console.log("Custom JS Initialized");
    // 示例：监听事件
    ctx.on("widget-click", (e) => {
      console.log("Widget clicked:", e.detail);
    });
  },

  /**
   * 更新时调用 (如配置变更)
   */
  update(ctx) {
    console.log("Custom JS Updated");
  },

  /**
   * 销毁时调用 (清理资源)
   */
  destroy(ctx) {
    console.log("Custom JS Destroyed");
    // 清理定时器、事件监听等
  },
};

⁠📜 开源协议

本项目采用 GNU AGPLv3⁠ 协议开源。

Enjoy your FlatNas! 🚀

Tag summary

Recent tags

Content type

Image

Digest

sha256:3006810ee…

Size

46.3 MB

Last updated

4 months ago

docker pull qdnas/flatnas