家庭服务器从入门到精通 · 第 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 现有方案的不足
| 方案 | 优点 | 缺点 |
|---|---|---|
| 浏览器书签 | 简单直接 | 跨设备同步难，维护成本高 |
| 静态导航页 | 可定制性强 | NPM变更需手动更新 |
| 第三方导航工具 | 功能丰富 | 与NPM数据隔离，配置复杂 |
1.3 理想方案的特征
- 自动同步：NPM配置变更后，导航站实时更新
- 权限控制：不同用户看到不同服务（如孩子只看学习、影音）
- 友好展示：服务分类、图标、中文名称
- 内外网统一：同一入口，自动适配网络环境
- 零额外配置：不增加NPM使用复杂度
核心洞察：NPM已经存储了所有代理配置，我们只需要一个"只读消费者"来展示这些数据。
二、技术原理：NPM数据库直读方案
2.1 NPM数据存储结构
NPM使用SQLite存储所有配置，Docker容器内的默认路径：
/data/database.sqlite关键表结构分析：
proxy_host表（代理主机配置）
| 字段 | 类型 | 说明 | 示例值 |
|---|---|---|---|
id | INTEGER | 主键 | 1 |
domain_names | TEXT | 域名列表（JSON数组） | ["nav.yourdomain.top", "www.nav.yourdomain.top"] |
forward_host | TEXT | 转发目标主机 | 192.168.1.100 |
forward_port | INTEGER | 转发端口 | 5000 |
ssl_forced | INTEGER | 强制SSL | 1（是）/0（否） |
enabled | INTEGER | 是否启用 | 1（启用） |
created_on | DATETIME | 创建时间 | 2026-06-15 10:30:00 |
advanced_config | TEXT | 高级配置（JSON） | {"custom_nginx_config": ""} |
access_list表（访问控制）
| 字段 | 说明 |
|---|---|
id | 访问列表ID |
name | 列表名称 |
enabled | 是否启用 |
2.2 核心设计思路
设计原则：
- 只读消费：绝不修改NPM数据库，避免锁表冲突
- 元数据分离：显示名称、分类、权限等存独立JSON文件
- 实时同步：每次页面加载都读取最新NPM配置
- 权限隔离：基于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 加了代理要手动同步 |
我的方案：自动读 NPM + 元数据增强。代理规则从 NPM 自动同步，显示名称和分类从proxy_metadata.json取。新加服务后，管理员在网页上修改一次名称和分类，后续自动生效——比手动维护整个家庭首页轻松得多。
八、使用效果
现在出差在外，打开手机浏览器：
- 输入
https://<你的域名>:<端口> - 弹出登录框，输密码
- 所有家庭服务一目了然
- 点一下进 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'十、总结
| 问题 | 解决方案 |
|---|---|
| 38 个子域名记不住 | 导航站集中展示 |
| NPM 加代理要手动同步 | 读 SQLite 自动同步 |
| 公网暴露不安全 | 账号密码认证 + HTTPS |
| 服务名不直观 | 网页内编辑显示名称 |
| 多人使用权限不同 | 卡片级权限控制 |
| 内外网都能用 | 相对 URL，走 HTTPS |
这就是家庭 HomeLab 的最后一块拼图——从硬件组网、网络优化、域名公网、端口映射、反向代理，到一站式的导航入口。整个体系闭环。
📸 截图占位：导航站首页分类展示、手机端响应式效果、登录弹窗、NPM 加代理后家庭首页自动出现
💡系列文章导航
本系列涵盖家庭服务器集群搭建、网络配置、Docker部署、AI应用等方方面面，适合有一定技术基础的读者。
（全文完）