家庭服务器从入门到精通 · 第 6 篇 · NPM代理到家庭首页导航中心全自动化智能化实现

家庭服务器从入门到精通 · 第 6 篇·NPM代理到家庭首页导航中心全自动化智能化实现

本文是「家庭服务器从入门到精通」系列文章，记录了从零搭建家庭服务器的完整过程。

系列：家庭服务器从入门到精通 · 第 6 篇
作者：妍杰丽云
标签：NPMPythonFlask自动化

引言：从38条代理到一键直达的智能导航

NPM（Nginx Proxy Manager）配好了，38条代理整整齐齐。但问题来了——你记得住38个子域名吗？每次想用某个服务，得去NPM面板翻一遍，或者维护一个越来越长的书签文件夹。要么你手动一个一个复制局域网地址、公网域名地址，建立一个家庭首页导航栏，增加一个服务，添加一个代理，就的需要自己去手动配置一条。有没有一种可能：NPM配好代理之后，家庭首页导航就自动更新，同时具备局域网地址和公网地址导航能力？当然有——而且实现起来比你想的简单。

本文原创方案：通过Flask直接读取NPM的SQLite数据库，实现零配置同步的家庭首页导航站。这可能是全网首个公开的"NPM数据库直读+动态权限管理"完整方案。

一、痛点分析：为什么需要智能导航站？

1.1 记忆负担：38+子域名的管理困境

第5篇配好了NPM，你的服务可以这样访问了：

nav.yourdomain.top:8443 → 家庭首页 jenkins.yourdomain.top:8443 → CI/CD git.yourdomain.top:8443 → 代码仓库 ai.yourdomain.top:8443 → AI面板 ...（还有34个）

现实问题：

• 记忆成本高：普通用户难以记住数十个不同子域名
• 操作繁琐：每次使用都要"打开NPM面板→查找域名→复制粘贴"
• 维护困难：手动维护书签，新增/删除服务时同步不及时

1.2 现有方案的不足

1.3 理想方案的特征

1. 自动同步：NPM配置变更后，导航站实时更新
2. 权限控制：不同用户看到不同服务（如孩子只看学习、影音）
3. 友好展示：服务分类、图标、中文名称
4. 内外网统一：同一入口，自动适配网络环境
5. 零额外配置：不增加NPM使用复杂度

核心洞察：NPM已经存储了所有代理配置，我们只需要一个"只读消费者"来展示这些数据。

二、技术原理：NPM数据库直读方案

2.1 NPM数据存储结构

NPM使用SQLite存储所有配置，Docker容器内的默认路径：

/data/database.sqlite

关键表结构分析：

proxy_host表（代理主机配置）

access_list表（访问控制）

2.2 核心设计思路

设计原则：

1. 只读消费：绝不修改NPM数据库，避免锁表冲突
2. 元数据分离：显示名称、分类、权限等存独立JSON文件
3. 实时同步：每次页面加载都读取最新NPM配置
4. 权限隔离：基于Session的多用户卡片级权限控制
   。

四、密码和权限控制

家庭首页暴露到公网了，不能谁都能看。需要加一道防盗门。

4.1 登录认证

我采用了HTTP Basic Auth + Session混合方式：前端是登录页面，后端用 Session 保持登录态。默认内置两个账户：

• 管理员：admin/your_admin_password（请务必修改）
• 普通用户：user/your_user_password

⚠️安全提醒：示例密码仅为演示，部署后请立即通过“修改密码”功能或直接编辑users.json更改。

4.2 为什么不用更复杂的认证

家庭场景，基于 Session 的账号密码认证已经足够：

• 实现简单，无需 OAuth 或 LDAP
• 配合 HTTPS 加密传输，密码不会明文泄露
• 支持多用户，且管理员可以细粒度控制权限

4.3 HTTPS 强制

所有对外服务（包括家庭首页本身）都应通过 NPM 强制 HTTPS 访问。NPM 会自动配置 Let’s Encrypt 证书，确保传输安全。

五、页面设计

家庭首页不需要花哨，实用第一。

5.1 分类展示

38 条代理分几个大类，一目了然：

┌──────────────────────────────────────────────┐ │ 🏠 我的家庭首页 │ │ 最后更新: 2026-06-28 14:30 (自动同步) │ ├──────────────────────────────────────────────┤ │ 🌐 网络工具 │ │ [NPM面板] [1Panel] [路由器] [旁路由] ... │ ├──────────────────────────────────────────────┤ │ 💻 开发工具 │ │ [Gitea] [Jenkins] [API文档] [IT-Tools] ... │ ├──────────────────────────────────────────────┤ │ 🤖 AI 服务 │ │ [QwenPaw] [Ollama] [FunASR] [SD绘图] ... │ ├──────────────────────────────────────────────┤ │ 🎬 影音娱乐 │ │ [Jellyfin] [有声书] [视频站] ... │ ├──────────────────────────────────────────────┤ │ 🏠 生活服务 │ │ [密码管家] [云盘] [HA] ... │ └──────────────────────────────────────────────┘

每个卡片：图标 + 服务名 + 点击直接跳转。内外网都可用。

5.2 响应式

手机、平板、PC 都自适应。外网用手机打开家庭首页，点一下就能进任何服务——这就是建家庭首页的初衷。

六、Docker 部署

家庭首页也是个 Docker 容器，跑在 webServer 上。

6.1 Dockerfile

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 5000 CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:5000", "app:app"]

6.2 docker-compose

nav-site:image:nav-site:latestcontainer_name:nav-siteports:-"5000:5000"volumes:# 只读挂载 NPM 数据库-/opt/1panel/apps/nginx-proxy-manager/nginx-proxy-manager/data/database.sqlite:/data/npm.sqlite:ro# 挂载配置文件（账户密码、名称映射）-./config.py:/app/config.py:rorestart:always

📌 关键：NPM 数据库以**只读（:ro）**方式挂载。家庭首页只读取，绝不写入，确保不会破坏 NPM 的数据。

6.3 NPM 代理

家庭首页本身的域名当然也走 NPM：

nav.yourdomain.top → <内网服务器>:5000 (导航站本身)

鸡生蛋蛋生鸡？不是问题——导航站是所有代理之一，NPM 配好这条后，导航站里也会显示它自己。

七、自动发现 vs 手动维护

我的方案：自动读 NPM + 元数据增强。代理规则从 NPM 自动同步，显示名称和分类从proxy_metadata.json取。新加服务后，管理员在网页上修改一次名称和分类，后续自动生效——比手动维护整个家庭首页轻松得多。

八、使用效果

现在出差在外，打开手机浏览器：

1. 输入https://<你的域名>:<端口>
2. 弹出登录框，输密码
3. 所有家庭服务一目了然
4. 点一下进 Jenkins，再点一下进聊天室，再点一下看电影

不需要记任何子域名，不需要翻书签。一个家庭首页，全家所有服务的中转站。

而且每次在 NPM 里加了新代理，刷新导航站就自动出现了——零额外维护。

九、安全与运维建议

9.1 密码安全

• 首次部署后立即修改默认密码（直接编辑users.json或通过网页修改）
• 使用强密码（至少 8 位，含大小写字母、数字、特殊符号）
• 定期更换密码

9.2 数据备份

家庭首页提供了一键备份导出/导入功能（管理员可见），可以将所有分类、元数据、手动链接导出为 JSON 文件。建议定期备份，以便迁移或恢复。

9.3 日志监控

Flask 应用默认输出日志到控制台，建议通过 Docker 的日志驱动收集，或配置logging模块写入文件，便于排查问题。

9.4 资源限制

在 Docker Compose 中可以添加资源限制，避免导航站占用过多内存或 CPU：

deploy:resources:limits:memory:256Mcpus:'0.5'

十、总结

这就是家庭 HomeLab 的最后一块拼图——从硬件组网、网络优化、域名公网、端口映射、反向代理，到一站式的导航入口。整个体系闭环。

📸 截图占位：导航站首页分类展示、手机端响应式效果、登录弹窗、NPM 加代理后家庭首页自动出现

💡系列文章导航
本系列涵盖家庭服务器集群搭建、网络配置、Docker部署、AI应用等方方面面，适合有一定技术基础的读者。

（全文完）