1ac8d2a0f2
docs: 修正过时端口(8080→18080)与 statusCheck 示例值
...
审计发现 README 三处过时:
- 快速开始示例 docker run -p 3003:8080(容器内 nginx 已是 18080)
- 遗留 portal-nginx 配置示例里 blog 上游仍写 8080
- 配置示例里 statusCheck: true(该项已按要求关闭,示例值应同步为 false 并注明原因)
2026-09-12 15:17:42 +08:00
16707bdfab
docs: 同步「常用服务」新机制(导航项点击计数)并补 nav-visit 接口
...
审计发现文档仍有旧描述,且新端点完全没写:
- README:分组注释/机制说明/系统分组警示/history-server 职责 仍写成泛指的"访问频次",
容易让人以为常用服务来自浏览器历史。统一改为"导航项点击次数(nav-visits.json)",
并明确两者数据源互相独立(常用服务不看浏览器历史)
- README 接口表 + AGENTS.md §4.2 补 POST /api/history/nav-visit 的可执行示例
- AGENTS.md 已知坑补一条:顺序不像"最常点的"时如何排查
2026-09-12 15:16:57 +08:00
a9845f1fba
feat(nav): 常用服务改为纯访问频次 top-5,取消 Gitea 置顶
...
用户要求:不要固定置顶 Gitea,且每个服务都应归到准确描述其功能的分组里。
- history-server/main.go:删除「强制 Gitea/代码托管置顶」逻辑(含 isCodeHostVal
参与的首位组装),改为按访问频次取前 5;顶部说明同步更正
- 文档:README / AGENTS.md 里"(Gitea 置顶)"的描述改为"不置顶任何服务"
- 现场分组调整:新建「代码托管」分组并把 Gitea 归入(此前它只存在于
系统管理的 常用服务 里,等于没有功能归属)
go vet / go test 通过。
2026-09-12 12:27:35 +08:00
7c3054f14a
docs: 明确 常用服务/历史访问 是系统管理分组,禁止手工加条目
...
用户指出:常用服务应当是按访问频次自动排序取前五,不该手工塞条目。
我部署 it-tools 时正是这么错的(把新项直接写进了 常用服务,污染频次榜)。
- AGENTS.md:写入导航条目示例前加警示(两个系统分组 + navSection 必须指向用户分组
+ 实测教训:塞进常用服务会被下次重建挤掉)
- README:配置接口章节加同样说明
现场已修正:IT Tools 移入「AI & 工具」,路由 navSection 同步改为该分组,
常用服务恢复为 4 项(系统按频次维护)。
2026-09-12 12:22:01 +08:00
5ba7789e30
docs(readme): 架构描述改为当前实态(单容器即统一入口 + 内置认证)
...
README 开头与架构图还停留在"portal-nginx + portal-auth + navi"三容器时代。
- 开头一句话改为:反向代理 + 统一登录 + Dashy + SearXNG + 历史 + 管理后台
+ 路由管理全在同一容器内,容器自己就是入口(3080/8443,3081 跳转)
- 架构图重画:公网 → frps → frpc → navi 单容器,容器内按 $host 查路由表分流、
需要登录的走 auth_request 到内置登录服务(:3005)、未知域名给自定义 404、
上游故障给自定义 500(错误页免认证)
- 容器内部图补:nginx 内部端口 18080(对外 3080/8443)、/auth/verify 认证校验、
gateway/*.conf 路由生成来源
- 明确标注 portal-nginx / portal-auth 已停用,仅作回滚保留
2026-09-12 11:11:28 +08:00
02b321ab51
docs: 拆分双版本教程 —— AGENTS.md(agent 照着做)+ README.md(人类)
...
用户要求:教程要能让 agent 跟着做,且区分 agent 版与人类版。
新增 AGENTS.md(可机械执行,不做叙述):
- §0 铁律 8 条(首装/升级不可混用、绝不重置门户口令、apply 后异步 reload、
/admin/api 前缀、路由表整表替换、脱敏清单、不 sed -i 单文件挂载、部署串行)
- §1 场景判定(一条命令区分首装/升级)
- §2 首装:前置检查、三组命令示例、**逐步期望输出**、5 条失败处置表
- §3 升级:硬性前提(旧容器无 cookie 域就必须传 NAVI_COOKIE_DOMAIN)、命令、
期望输出、收尾断言(含 navi-next 残留的处置)
- §4 配置:先取 /api/schema 清单,再给可直接照抄的六类写入命令 + **写完必须验证**
- §5 验收清单:五项探测及各自不符合时的含义
- §6 提交前脱敏清单(可执行命令 + 绝不可提交项 + "可配置项不得写死")
- §7 回滚 §8 已知坑(8 条,全部是本次实测踩过的)
README:顶部加"两种读者两个入口"导航,并在首装/部署两节加指向 AGENTS.md 的指引。
2026-09-12 10:50:02 +08:00
412e51d1f5
docs: 教程同步本轮全部变更(升级守卫 / 可配置项 / agent 接口)
...
- 升级示例补 NAVI_COOKIE_DOMAIN、NAVI_HOME_URL:旧容器没有 cookie 域且未传时
脚本会拒绝升级(否则登录 cookie 退化 host-only,跨子域登录失效)
- 升级脚本环境变量表补齐:NAVI_COOKIE_DOMAIN / NAVI_HOME_URL / NAVI_CHECK_HOST /
NAVI_ROTATE_PORTAL_PASSWORD,并写明**默认不改登录口令**(生效凭据是数据卷里的加盐哈希,
改口令会让所有受保护域名立即要求新口令,属高风险,必须显式开启)
- 自定义文件表补 pages.go(文案渲染 + 卡片覆盖)与 schema.go(/api/schema 配置清单)
- 门户卡片章节补后台入口(站点信息 → 门户页服务卡片,与接口同一份数据)
- 自检域名说明:脚本内不写死任何域名,默认取路由表首条(避免脱敏改坏自检)
2026-09-12 10:47:41 +08:00
203cd05fbb
docs: 接口注意事项(前缀 / 整表替换 / 必须 apply / reload 需等待)
...
验证过程中实际踩到的四点,写进 README 便于 agent 与人复用:
1. 管理接口前缀是 /admin/api;打根 /api/ 会拿到 200 + Dashy HTML 的假成功,
判断是否命中要看返回体类型而非状态码
2. 路由表是整表替换,必须提交完整 {routes:[...]};清空非空表需 force:true
3. 改完必须 apply(内部 nginx -t 校验,失败保留旧配置并回显 nginx 报错)
4. apply 是异步 reload:立刻探测会得到旧结果(表现为'apply 了却 404'),
给出轮询等待入口就绪的示例脚本
2026-09-12 10:31:46 +08:00
bb41b61ad6
fix(gateway): 路由表接口只替换路由,不再整份配置重置(agent 友好)
...
真实验证(干净环境练兵)抓到:POST /admin/api/gateway/routes 会把整个
GatewayConfig 反序列化为零值后保存,因此
- 只提交单个路由对象 → {"routes":0,"status":"saved"}:**静默清空整张路由表**
- 提交 {"routes":[…] } → 其余字段被重置为默认(实测入口端口 13080 → 8081,
TLS/认证地址一并丢失),随后 apply 生成的配置与预期完全不符
对 agent 尤其危险:照文档提交一条路由就会改掉入口端口与所有其它路由。
修复:
- 只补路由表:以现有配置为基准,仅替换 Routes,其它字段原样保留
- 请求体必须是 {"routes":[...]};缺该键 → 400 并说明正确形状(不再静默变空表)
- 非空表要清空必须显式传 force:true,否则 400 拒绝
- 测试:单个对象被拒;数组提交后 listenPort/TLS/认证地址/证书路径全部保留;
清空被拒、force 允许
- README:修正路由示例为完整数组形状,补"替换整张表"与 /admin/api 前缀说明
2026-09-12 10:28:03 +08:00
92fd32e7a9
feat(api): 全量配置项暴露为接口 + 后台增加门户卡片编辑框
...
用户要求:所有可配置项都应当是 API,方便 agent 直接把站点配成用户喜欢的样子。
- 新增 GET /api/schema:一次返回
· items:全部单值配置项(站点信息、登录页/门户页文案、备案号、页脚…),
含当前值、类型、写入口与请求体示例;**当前为空的键也会列出**,否则 agent 发现不了
· resources:结构化资源与其真正的写入口(导航、路由表+apply、门户卡片、壁纸、
门户口令、历史、图标上传、重载),并在 hint 里写明"路由表改完必须 apply"这类约束
- 后台「站点信息」新增「门户页服务卡片」编辑框:载入 / 保存 / 清空即回内置,
与 /api/portal-cards 同一份数据(界面能改的 agent 都能改)
- README 新增「配置接口(agent 可直接改)」:schema 用法、写入口对照表、可直接复制的示例
- 测试:schema 必须列出关键项与写入口;卡片接口写入生效、清空返回 reset 并回落内置
2026-09-12 10:19:22 +08:00
7c2bed2f2d
feat: 门户页卡片可配置 + 升级前域名校验 + 清理明文门户口令
...
按用户选择实施三件事:
1) 门户页服务卡片可配置(不再写死真实域名)
- portal/index.html 卡片区加 <!--NAVI_CARDS_START/END--> 标记,内置卡片改为通用示例
- renderPortalPage 支持数据卷 <data>/portal/cards.html 覆盖标记区间(清空即回落内置)
- 新增 GET/POST /api/portal-cards 读写该片段
- 测试:覆盖替换成功、空白片段回落内置
- 仓库内真实域名由此清零
2) 升级前必须提供跨子域单点登录变量(防止"去掉写死默认值"造成 SSO 静默失效)
- zd-host.sh 在切换前检查 PORTAL_COOKIE_DOMAIN:缺失且未传 NAVI_COOKIE_DOMAIN
时直接拒绝升级(退出码 2)并给出正确命令;PORTAL_HOME_URL 可用 NAVI_HOME_URL 补
- README 新增「升级已有部署前必须确认的两个变量」含失败表现与正确命令
3) 清理明文门户口令
- 迁移旧容器 env 时丢弃 PORTAL_PASSWORD(docker inspect 可见 = 泄露面)
- 升级后写入强随机口令并通过接口生效,部署日志只打印一次;失败不阻断升级并提示后台可改
2026-09-12 10:14:22 +08:00
b99319b38b
chore(sanitize): 备案号与域名一律可配置,仓库不再预置真实域名/备案号/内网地址
...
用户要求:备案号与域名都应当可配置,仓库内容要脱敏。
功能(不只是替换字面量):
- 被代理页面注入的备案号改为读后台「站点信息」的 icp/gongan,**未配置就不注入**;
原先写死具体备案号,等于每个部署者都会把别人的备案信息印到自己页面上
- 注入内容做 nginx 安全处理(去引号/反斜杠/换行/美元符),并有测试覆盖
- auth.go:PORTAL_COOKIE_DOMAIN / PORTAL_HOME_URL 不再预置域名,
cookie 默认 host-only、首页默认相对路径 "/"
- gateway.go:默认 loginUrl 不再预置域名(受保护路由缺配置会明确报错,不静默生成跳不出去的登录页)
- 首装脚本在给了 NAVI_DOMAIN 时自动注入 PORTAL_COOKIE_DOMAIN/PORTAL_HOME_URL,
避免"去掉写死默认值"导致跨子域单点登录失效
脱敏:内网 IP(10.0.0.10)与真实备案号清零;真实域名仅剩门户页内容 8 处(待定);
测试夹具/示例/错误页/脚本/后台占位提示全部通用化。
README:新增「跨子域单点登录需要的两个环境变量」;环境变量表改为 NAVI_HOST 必填。
测试:新增备案号注入三条(用配置、未配置不注入、危险字符清理)。
2026-09-12 10:10:52 +08:00
c0cbdb5efc
feat(deploy): 补首装路径,使他人/AI 可照教程从零部署
...
审计发现 5 处断点(3 处硬阻断):
1. Dockerfile 的 HTTP_PROXY/HTTPS_PROXY 默认指向内网代理 → 他人构建必失败
2. zd-host.sh 是升级脚本(要求已存在 host 模式 navi 容器)→ 新机器第一句过不去
3. docker-compose.yml 是桥接+端口映射,与'统一入口 host 模式'口径冲突
4. 证书文件名约定未文档化(实际来自 gateway.yml 的 certFile/keyFile)
5. 环境变量表不完整、缺 sshpass 依赖说明
本次:
- Dockerfile:代理默认置空,需要时 --build-arg 传入
- deploy/install-host.sh(新):干净机器首次安装,6 步并在任一步失败即停,
含端口独占检查、证书检查、初始 gateway.yml 生成、apply、四项自检,
令牌可自动生成并只打印一次;已存在 navi 容器时拒绝执行(引导去 zd-host.sh)
- docker-compose.yml:标注为试用形态,指向 install-host.sh
- README:新增「从零部署(干净机器)」——两条路径分工表、前置条件表、
完整环境变量表、证书与初始网关配置说明、装完自检命令;自定义文件表登记新脚本
另修:脚本自检原用 /.navi-ping(该路径已按用户要求删除),改用 /conf.yml。
2026-09-12 09:37:45 +08:00
472d8d1cd0
feat(pages): 认证页与门户页文案可配置,不再写死
...
需求:登录页与门户页的内容应可自定义。
实现(配置存数据卷、后台可改、留空回落内置默认,不配置行为不变):
- pages.go:pageStr 读取 pageInfo;renderPortalPage 优先数据卷
<data>/portal/index.html 整页覆盖,否则用内置模板替换占位符;
authPageInfo 提供登录页字段
- auth.go:登录页标题/副标题/徽标/页脚改为模板数据(含备案号)
- gateway.go:kind=portal 的首页改由 admin-server /portal-page 渲染
(静态资源仍由 nginx 提供),使文案可配置
- portal/index.html:加入 <!--PAGE_TITLE--> / <!--HERO_TITLE--> /
<!--HERO_SUBTITLE--> / <!--FOOTER--> 占位符
- 后台「站点信息」新增六项文案输入(含回填与保存),并提示整页覆盖方式
- README 新增「认证页与门户页文案(可配置,不写死)」含字段表与自检命令
测试:默认回落、配置取值去空白、认证页字段读取、数据卷覆盖优先、空白覆盖忽略。
2026-09-12 09:12:13 +08:00
352aa570ec
chore: 验收脚本入库(矩阵/工作空间/滚动)+ 修正脱敏自检命令
...
- deploy/verify-matrix.js:6 尺寸 × 3 视图 × 深浅色矩阵,断言纵向滚动(仅
minimal/workspace)、文字亮度阈值、深色是否生效、零运行时异常
- deploy/verify-workspace.js:触发 workspace blocked 态,读弹窗卡片 computed style
- deploy/verify-scroll.js:多视口滚动复现(含 900x520 这类矮窗口)
三者只从环境变量 PORTAL_COOKIE 取会话,无任何硬编码凭据
- README 自检命令改为排除占位符(<...>、${VAR:-}、change-me),避免误报
- 自定义文件表登记上述脚本
2026-09-12 08:55:04 +08:00
323d494615
docs: 补齐一体化模式教程、自定义文件清单与脱敏清单
...
- 新增「一体化模式」章节:单容器即统一入口(TLS + 统一登录 + 导航 + 搜索 + 历史/管理)
· 端口与挂载(内部 18080 / 对外 3080、8443 / 跳转 3081;data 卷 + 证书只读卷)
· host 模式部署命令与失败自动回滚;说明 zd.sh 双端口轮换在合并后失效的原因
· 切换四步、服务转发字段(含逐条统一认证与导航绑定)、现有 nginx 配置导入
· 统一登录账号(数据卷存加盐哈希,优先级与生效方式)
· 深浅色/壁纸/状态点关闭的原因(含 background 简写清掉壁纸的坑)
· 回滚路径(容器、配置备份、数据卷)
- 「部署需要的全部自定义文件」表补充:deploy/zd-host.sh、portal/、auth.go、
gateway*.go、portal_auth.go
- 新增「绝不提交的内容(脱敏清单)」:conf.yml/备份、各类 token 与口令、portal-auth.json、
证书、运行时 env 与 nginx 备份;并给出两条发布前自检命令
- 零停机部署与 portal-nginx 两节加指引,避免照旧流程操作
2026-09-12 08:54:33 +08:00
a6b5513f88
docs+chore: 部署脚本入库、README 补零停机部署与部署物料清单
...
仓库此前缺少部署脚本,只能靠临时文件操作,新人无法复现。补齐:
- deploy/zd.sh:零停机部署(新容器先在对侧端口验证到底,含 /search 预热
SearXNG;再同 inode 覆写门户上游 + nginx -t + reload;切后哨兵"不得为 502";
失败自动回滚,旧容器保留为回滚点)。可用环境变量覆盖主机/路径/镜像。
- deploy/verify-ui.js:部署后浏览器验收(渲染开销、后台窄屏、收边两段式、
被拒内嵌弹层、分组增删改与「历史访问」保护)。任一运行时异常即判失败。
README 新增:
- 「零停机部署」含**单文件 bind mount 不能用 sed -i** 的坑(换 inode → 容器读到
旧值 → 全站 502,本项目真实踩过)与正确顺序(同 inode 覆写 → 断言容器看到 →
nginx -t → reload)
- 「部署需要的全部自定义文件」清单表
- 「管理后台」补分组自由增删、历史分组保护、完整 API 表
- 「工作空间视图」补可内嵌性三态探测(转发 Cookie、WAF 403 误判)、被拒弹层、
悬浮控件收边与"第一次交互只滑出"
2026-09-11 20:13:44 +08:00
6fd62d4949
docs: note that the install page shows the sync token
...
安装引导页已展示服务地址与同步令牌;README 补充说明令牌来源
(/admin/api/sync-info,位于门户登录墙内,不能挂在被放行的 /api/ 下)。
2026-09-11 11:52:17 +08:00
aa237868c1
feat(deploy): let data volume override SearXNG settings
...
SearXNG 的配置原本只能靠镜像内置的 /etc/searxng/settings.yml,
于是代理(outgoing.proxies)这类部署相关配置每次重建容器都会丢,
改配置也必须重建镜像。
改为:容器启动时若存在 /app/data/searxng-settings.yml 就用它,
否则回退到镜像内置配置。用 sh -c 包一层是因为 supervisord 的
environment= 不支持条件判断。
注意必须带 [ -f ] 判断:实测 SEARXNG_SETTINGS_PATH 指向不存在的
文件时 SearXNG 会直接报错退出(PermissionError: ... not exists!)。
已验证:SEARXNG_SETTINGS_PATH 指向自造配置能正确覆盖端口与实例名。
README 补充配置优先级与数据卷备份清单。
2026-09-11 11:09:33 +08:00
73396cd5d4
docs: document NAVI_FAVICON_PROXY and pass it through compose
...
新增的 favicon 抓取代理变量此前只存在于代码里:
- .env.example 补充说明与示例(默认留空,自动复用 SearXNG 的 outgoing.proxies)
- docker-compose.yml 透传该变量
- README 环境变量表补一行
2026-09-11 11:00:40 +08:00
e7ea091e19
fix(history): give history entries real site favicons
...
历史条目的图标原先写死 fas fa-globe,整栏都是地球图标。
- 新增 history-server/favicon.go:后台抓取每个 host 的 favicon 并缓存到
data/item-icons/,命中后 conf.yml 写本地文件名,与手工图标同一套解析。
抓取顺序 <host>/favicon.ico → 首页 <link rel=icon>;3 个 worker,
失败 6 小时后再试;完成后合并触发一次 conf.yml 重建。
- 只缓存 Dashy 能渲染的格式:其 isImage() 白名单是 [svg,png,jpg],
写 .ico 进去完全渲染不出来。因此 .ico 先抽内嵌 PNG,若是传统 BMP/DIB
编码则解码后转 PNG(Google 这类站点只给老式 .ico)。
- 内网地址用 host:port 区分(不同端口的服务不再共用一个图标),且只直连;
外网站点直连失败时自动复用 SearXNG outgoing.proxies 的代理,
也可用 NAVI_FAVICON_PROXY 覆盖。
- 修掉一个真实缺陷:导航项都没有访问数据时,原来会提前 return 并把
「历史访问」清成只剩安装入口 —— 只浏览站外站点时真实历史会整个消失。
现在只冻结「常用服务」,历史照常生成。
- Dockerfile 去掉 # syntax=docker/dockerfile:1:该指令会让 BuildKit 去 pull
docker/dockerfile 前端镜像,无外网环境直接构建失败;本文件未用 BuildKit 语法。
实测:6/6 站点(含 google.com 的 DIB 型 ico、github.com、docker.com、
news.ycombinator.com 与两个内网服务)均得到真实图标,页面 naturalWidth>0。
2026-09-11 10:55:00 +08:00
ff0e6418f8
feat(nav): auto-detect browser extension and offer one-click install
...
导航页现在会自动检测浏览历史插件是否已安装:
- 扩展在用户配置的服务地址上动态注册 content script
(Chrome: chrome.scripting.registerContentScripts,
Firefox: browser.contentScripts.register),
于 document_start 给 <html> 打上 data-navi-ext 标记,
不在其他站点运行。
- history-server 始终把「安装浏览历史插件」放在「历史访问」第一条
(入口 url=/extension/install.html),启动时也会重建一次,
不再需要等下一次同步。
- web/navi.js 读到标记后隐藏该入口(连 .item-wrapper 一起隐藏,
避免留下空网格位)。
- 新增 /extension/install.html:自动识别浏览器,给出对应安装包与步骤;
支持在 data 卷放 extension-store.json 配置商店链接,
有商店链接时显示真正的「一键安装」。
- 段落名匹配同时兼容中英文(常用服务/Favorites、历史访问/History),
修掉了公开示例 conf.yml 用英文名时重建逻辑完全失效的问题。
- 扩展升到 1.1.0(新增 scripting 权限与 detect.js)。
Note: Chrome/Edge 不允许从网站直接安装非商店扩展,
因此自托管场景下只能下载后手动加载;发布到商店后才会出现一键安装。
2026-09-11 10:41:10 +08:00
88e23861fe
fix(search): repair SearXNG engine failures
...
- bing: www.bing.com 302-redirects to cn.bing.com and SearXNG engine
requests do not follow redirects, so it parsed the 178-byte redirect
page and returned 0 results without any error report. Point bing at
https://cn.bing.com to bypass the redirect.
- Raise outgoing request_timeout 3.0 -> 8.0 and max_request_timeout
4.0 -> 15.0. max_request_timeout overrides each engine's own timeout,
so 360search (timeout 20s) was still cut off at 4s.
- Enable duckduckgo (verified working) and disable baidu/sogou which
return 302 verification pages (baidu also hits a 1h CAPTCHA ban, and
sogou raises AttributeError on SXNG_Response.next_request).
- Document the diagnosis in the README FAQ.
2026-09-11 10:26:32 +08:00
33564fb8f5
docs: complete deployment tutorial + frp/webui4frpc guide, expand .env/docker-compose for tokens & base_url
...
- Rewrite quick-start for source clone & build (A: compose, B: docker run)
- Expand frp section: full frps.toml, webui4frpc WebUI workflow, native frpc.toml, tunnel planning table
- docker-compose: NAVI_PORT / SEARXNG_BASE_URL env passthrough, better docs
- .env.example: document all vars incl token generation & base_url
- Fix firefox debugging URL typo, extension token note
2026-09-08 22:39:52 +08:00
76a4265222
docs: fully sanitize README (remove host identifiers .60/.106)
2026-09-08 22:25:57 +08:00
7e49d2b51c
feat: HomeDash - unified self-hosted navigation portal
...
Single-container navigation service combining:
- Dashy dashboard + SearXNG metasearch + history sync API + admin WebUI
- Go services for history/admin APIs, nginx as unified entry
- Browser extensions (Chrome MV3 / Firefox MV2) with 30s batched sync
- Production guide: portal-nginx unified auth reverse proxy + webui4frpc/frp tunnel
- Fully sanitized (no internal IPs/domains/credentials)
2026-09-08 22:25:00 +08:00