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

家庭服务器从入门到精通 · 第 6 篇·NPM代理到家庭首页导航中心全自动化智能化实现本文是「家庭服务器从入门到精通」系列文章记录了从零搭建家庭服务器的完整过程。系列家庭服务器从入门到精通 · 第 6 篇作者妍杰丽云标签NPMPythonFlask自动化引言从38条代理到一键直达的智能导航NPMNginx 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表代理主机配置字段类型说明示例值idINTEGER主键1domain_namesTEXT域名列表JSON数组[nav.yourdomain.top, www.nav.yourdomain.top]forward_hostTEXT转发目标主机192.168.1.100forward_portINTEGER转发端口5000ssl_forcedINTEGER强制SSL1是/0否enabledINTEGER是否启用1启用created_onDATETIME创建时间2026-06-15 10:30:00advanced_configTEXT高级配置JSON{custom_nginx_config: }access_list表访问控制字段说明id访问列表IDname列表名称enabled是否启用2.2 核心设计思路NPM管理界面修改代理配置写入 database.sqliteFlask导航站只读模式访问读取proxy_host表解析域名/端口/SSL结合metadata.json生成分类导航页用户访问管理员修改metadata.json设计原则只读消费绝不修改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 DockerfileFROM 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-composenav-site:image:nav-site:latestcontainer_name:nav-siteports:-5000:5000volumes:# 只读挂载 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 代理家庭首页本身的域名当然也走 NPMnav.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 中可以添加资源限制避免导航站占用过多内存或 CPUdeploy:resources:limits:memory:256Mcpus:0.5十、总结问题解决方案38 个子域名记不住导航站集中展示NPM 加代理要手动同步读 SQLite 自动同步公网暴露不安全账号密码认证 HTTPS服务名不直观网页内编辑显示名称多人使用权限不同卡片级权限控制内外网都能用相对 URL走 HTTPS这就是家庭 HomeLab 的最后一块拼图——从硬件组网、网络优化、域名公网、端口映射、反向代理到一站式的导航入口。整个体系闭环。 截图占位导航站首页分类展示、手机端响应式效果、登录弹窗、NPM 加代理后家庭首页自动出现系列文章导航本系列涵盖家庭服务器集群搭建、网络配置、Docker部署、AI应用等方方面面适合有一定技术基础的读者。全文完