为什么觉得它有意思#

我手机上跑着虚拟机挂机，具体挂的什么就不细说了，反正需要 7×24 开着。问题是这玩意每隔几小时就会卡死一次，卡死之后只能手动打开虚拟机软件、把里面的两个实例重新启动。人不在手机边上的时候就断了，很烦。

这类”定时巡检 + 自动恢复”的活，以前要么自己写无障碍脚本，要么用 Tasker 拼，都挺麻烦的。看到 Operit 支持无障碍、Shizuku、Root 三种通道直接操作手机界面，还能跑工作流和定时任务，就想着：能不能让 AI 直接帮我搞定这事？

排查过程#

我直接把问题丢给它：虚拟机每隔几小时卡死，帮我看看怎么回事。

它先是翻日志、看进程状态，分析了一圈可能的原因——内存回收、后台限制这些都查了一遍。说实话具体原因到最后也没 100% 定位，虚拟机这种东西卡死的因素太多了。但它换了个思路：既然不好根治，那就盯着它，卡死了自动拉起来。

然后它给我写了一个看门狗程序：持续检测虚拟机的运行状态，一旦发现卡死，自动打开虚拟机软件，然后把里面的两个实例依次启动起来。整个过程不用我管。

跑了几天，挂机再没断过。偶尔看记录，看门狗半夜自己触发过几次重启，早上起来虚拟机好端端的跑着。

它能干什么#

除了这次用到的自动化能力，看了下 README，功能面铺得挺广的：

• AI 对话：兼容 OpenAI、Anthropic、Gemini 各种端点，也能跑本地模型（内置 MNN，支持 GGUF）
• 设备自动化：无障碍 / Shizuku / Root 三种通道，能模拟点击、读屏、操作界面
• 内置终端：自带 Ubuntu 24.04 ARM64 用户空间，SSH、tmux、vim 都有
• 工作区：能直接在手机上开 Web、Python、Go 项目，代码编辑加实时预览
• 工作流：可视化编排，支持定时、Tasker、Intent、语音触发
• 其它：长期记忆、角色卡、多标签浏览器、语音对话、悬浮窗，一堆

对我来说核心就一条：它是真的能动手的 Agent，不是只会聊天的那种。

权限这块要说一下#

我自己的感受：有 Root 才是完全体。

UI 自动化这三档通道，能力差距挺明显的：

• Root：什么都能干，还能用虚拟显示，后台跑任务不挑场景
• Shizuku：ADB 级权限，大部分操作没问题，不用解锁 BL，应该是多数人的选择
• 无障碍：能用，但受系统限制多，碰到敏感界面就抓瞎

我这次是看门狗检测到卡死后要去启动应用、点界面，有 Root 就完全没阻碍。没 Root 的话 Shizuku 应该也不错，至少比我之前试过的纯无障碍方案靠谱。

几个细节#

• 系统要求：Android 8.0+，只要 ARM64 设备，APK 直接从 Releases 下
• 协议：LGPL-3.0，开源。作者还在做跨平台的 Operit 2（Rust + Flutter）
• 权限控制：工具调用分”自动允许、每次询问、禁止”三档，默认询问，不会背着你乱来
• 语言：界面支持八种语言，中文没问题

我的判断#

这类”手机上的 AI Agent”项目最近不少，但大部分停留在”能调用几个 API”的水平。Operit 是真的把触手伸进系统里了——终端、文件、界面操作、定时任务都能串起来，这次看门狗的事就是个例子：从排查问题到写脚本到落地执行，全程在它里面完成。

适合什么人：手机上有 Root 或愿意装 Shizuku、喜欢折腾自动化、想让 AI 干实事而不只是聊天的人。

不适合什么人：只想找个开箱即用的 AI 聊天工具的。这东西功能多，设置项也多，得花点时间摸索。

反正我现在挂机是彻底放心了。以后手机上再有这种重复性的脏活，估计都会先丢给它试试。

先把那些英文术语整明白#

搞缓存绕不开一屏幕英文，先把它们按”谁在看、谁在听”分好类，后面看配置就不晕了：

几个关键关系再说细一点：

• max-age 和 s-maxage 是分开的两个开关：s-maxage 拉得再长，浏览器也只认 max-age。所以可以做到”CDN 缓存一天，浏览器每次重新验证”。
• HIT 不丢人，MISS 也不丢人。第一次请求必然是 MISS（缓存是空的），第二次开始才是 HIT。判断缓存配好没，就是看同一个页面第二次请求是不是 HIT。
• 重新部署为什么能”自动清缓存”：Vercel 每次部署会主动把旧缓存失效掉。所以 HTML 的边缘缓存 TTL 设多长其实无所谓——反正部署时就换新的了。

分层配置 vercel.json#

思路很简单：不同文件用不同缓存策略。哈希资源一年不用动，HTML 要保证发新文章立即可见，数据接口折中。我的 vercel.json 最终长这样（安全头那部分是之前就有的）：

1
{
2
  "headers": [
3
    {
4
      "source": "/(.*)",
5
      "headers": [
6
        { "key": "X-Content-Type-Options", "value": "nosniff" },
7
        { "key": "X-Frame-Options", "value": "SAMEORIGIN" },
8
        { "key": "X-XSS-Protection", "value": "1; mode=block" },
9
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
10
        { "key": "Cache-Control", "value": "public, s-maxage=86400, stale-while-revalidate=604800, max-age=0, must-revalidate" }
11
      ]
12
    },
13
    {
14
      "source": "/_astro/(.*)",
15
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
16
    },
17
    {
18
      "source": "/assets/(.*)",
19
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=2592000, stale-while-revalidate=604800, must-revalidate" }]
20
    },
21
    {
22
      "source": "/(pagefind|pio)/(.*)",
23
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=2592000, stale-while-revalidate=604800, must-revalidate" }]
24
    },
25
    {
26
      "source": "/api/(.*)",
27
      "headers": [{ "key": "Cache-Control", "value": "public, s-maxage=3600, max-age=0, must-revalidate" }]
28
    }
29
  ]
30
}

每条规则的意图：

后续优化：给缓存加”过期续命”#

上面这套配置跑了几天，有个小毛病一直没解决：每天凌晨缓存过期那一刻，第一个访客要干等回源，快则几百毫秒，慢则一两秒，全看 Vercel 源站当时的状态。

2026-09-10 给 HTML 规则加了 stale-while-revalidate=604800：

1
"public, s-maxage=86400, max-age=0, must-revalidate"
2
"public, s-maxage=86400, stale-while-revalidate=604800, max-age=0, must-revalidate"

意思是：缓存过期后 7 天内，CDN 先把旧页面秒开给访客，同时在后台悄悄去源站拉新页面，拉完更新缓存，下一个访客看到的就是新的。这 7 天是兜底窗口，正常部署会主动清缓存，根本用不上；真出了异常也有旧页面顶着，不会白屏。

改完用 curl -sI 验证，响应头里能看到新指令：

1
curl -sI https://www.9ll.uk/ | grep -i cache-control
2
# Cache-Control: public, s-maxage=86400, stale-while-revalidate=604800, max-age=0, must-revalidate

这个改动和原来的 s-maxage=86400 是互补关系：一天内正常缓存，一天到七天之间过期续命，七天之后彻底重新验证。浏览器端 max-age=0 不变，发新文章依旧立即可见。

部署后自动预热#

配置完之后还有一个空窗期：新部署的缓存是空的，每个页面都要等第一个访客来”暖场”，第二个访客才能吃到缓存。我的站一共六十多个页面，全等真人来暖，得等挺久。所以抄第二篇文章的思路，加了个 GitHub Actions 工作流。

逻辑是这样的：

1
on:
2
  push:
3
    branches: [HY]        # 我的部署分支
4
  workflow_dispatch:       # 也能手动跑
5

6
jobs:
7
  warm:
8
    steps:
9
      - name: 等待 Vercel 完成新部署
10
        if: github.event_name == 'push'
11
        run: sleep 120
12
      - name: 预热并统计命中率
13
        run: bash .github/scripts/cache-warm.sh

脚本干三件事：从 sitemap-index.xml 逐片抓全站 URL → 并发 curl 每个页面一遍 → 读响应里的 X-Vercel-Cache 统计 HIT 率，没达标就歇 20 秒再来一轮，最多四轮。原文的做法是写个 HIT.txt 提交回仓库，我嫌提交污染提交历史，改成直接把统计打到 Actions 的运行日志里，点开就能看。

有个物理限制得说清楚：GitHub Actions 的机器在美国，预热的是美区边缘节点。Vercel 边缘缓存按区域分片，所以这个工作流不能保证国内节点也全绿——国内访客第一次访问某页面时，就近节点可能还是 MISS，回源一次之后就好了。想连这块都解决就得动 DNS 优选，那是另一个话题。

踩坑：header 顺序比你想象的阴险#

第一版配置我是把 HTML 那条规则单独放在 headers 数组最后面，想着 Vercel 应该会”更细的规则覆盖更宽的”。结果上线一测，/_astro/ 的 CSS 返回的头居然是 s-maxage=86400, max-age=0——immutable 没了。

查了文档才知道：Vercel 的 headers 匹配是先到先得，第一条 /(.*) 基础规则把后面所有细规则全挡了。修复也简单：把 HTML 的缓存头直接并进第一条基础规则，让每个请求在第一条就拿到该拿的头，后面的细粒度规则才有机会覆盖。

修完重新部署，再测：

1
curl -sI https://www.9ll.uk/ | grep -i cache-control
2
# Cache-Control: public, s-maxage=86400, max-age=0, must-revalidate
3

4
curl -sI https://www.9ll.uk/_astro/_..BulBwWNp.css | grep -i cache-control
5
# Cache-Control: public, max-age=31536000, immutable

这回对了。教训记下来：在 Vercel 配 headers，永远先声明通用头，再声明细粒度头，同 key 谁先声明谁赢。

验证效果#

配置生效后，冷态实测（第一次就请求）：

预热脚本本地冒烟测试的数据也放一下：64 个页面，第一轮 HIT 28/64（43.8%），第二轮 64/64（100%）。这就是”暖场”的效果，第一遍全是 MISS，第二遍全 HIT。

发新文章会不会被缓存卡住？不会。浏览器端是 max-age=0, must-revalidate，每次都会带着 ETag 去问边缘节点有没有新版，部署一完成，刷新就是新内容。

写在最后#

整套东西在 Vercel 上就是一个 vercel.json + 一个 Actions 工作流，后台什么都不用点。对静态博客来说，s-maxage 边缘缓存加哈希资源 immutable 基本就是全部了，剩下的预热属于锦上添花。如果你也想抄，顺序记住：

1. vercel.json 里通用头写进第一条规则，细粒度规则放后面
2. HTML 用 s-maxage 控制边缘、max-age=0 控制浏览器
3. 带哈希的资源大胆上 immutable
4. 加个部署后预热工作流，消掉”第一个访客最慢”的空窗

配置完用 curl -sI 看响应头就行，同一个 URL 连请求两次，第二次 X-Vercel-Cache: HIT 就成了。

第一版翻车：光看概述就动手#

一开始我没去扒源码，让 AI 帮我”描述一下这个页面长什么样”，照着那个概述做了个版本：一个卡片加几条列表。

结果被自己打脸了。和源站的出入大到没法看——人家是 hero 统计卡加时间线加大卡片，我做出来的是个毛坯。最讽刺的是我还写了个”详细记录”，把写博客文章这种事也塞进了变更明细。

痛定思痛，还是老老实实扒源码。

扒站：把 HTML 和 CSS 都拆出来#

第一步是 curl 把页面和它自己的样式文件都拉下来：

1
curl -sL https://rainzt.cn/blog-changelog/ -o changelog.html
2
# 从 HTML 里找到它引用的样式文件
3
grep -o 'blog-changelog[^"]*\.css' changelog.html
4
# 再把这个 CSS 也拉下来
5
curl -s https://rainzt.cn/_astro/blog-changelog.A9uhDpGh.css -o changelog.css

然后对着 HTML 的结构一层层拆，它的页面骨架长这样：

1
blog-changelog-page
2
├── hero（眉线 + 标题 + 描述 + 版本规则 + 2×2 统计卡）
3
├── nav（返回链接 + 按日倒序说明）
4
└── ol.list（时间线）
5
    └── li.entry × N
6
        ├── date（日期 + 第几次记录）
7
        ├── rail（圆点 + 轴线）
8
        └── article.card（版本徽章 + kind 短语 + h2 + 描述
9
            + details 折叠明细 + tags）

关键细节在 CSS 里：时间线轴线是一条渐变的 1px 竖线，圆点是主题色带光环（box-shadow: 0 0 0 .22rem），折叠明细用原生 <details> 配展开动画，箭头旋转 180 度。这些光看概述是绝对看不出来的。

重做：全部塞进三个新文件#

照着结构重做了一版。和首页贴纸一样，我给自己定的规矩是不碰主题源码，方便以后合并 CuteLeaf/Firefly 上游的更新。所以拆成三块：

这个方案最舒服的地方是记日志完全不用碰代码，往配置里加一个对象就行：

1
{
2
    version: "V1.0",
3
    title: "首页贴纸卡片",
4
    date: "2026-09-06",
5
    summary: "首页来了套新皮肤",
6
    description: "给首页壁纸区加了一套可拖拽的贴纸装饰和个人卡片……",
7
    items: [
8
        { category: "首页", text: "新增壁纸装饰卡片……" },
9
        { category: "视觉", text: "贴纸布局按列对齐……" },
10
    ],
11
    tags: ["首页", "贴纸", "视觉", "移动端", "性能"],
12
}

样式全部复用 Firefly 的主题变量（--line-divider、--content-meta、--card-bg、--primary），深浅色模式自动适配，一行硬编码颜色都不用写。

怎么用：记一次日志只需要动一个文件#

所有数据集中在 src/config/blogChangelogConfig.ts，加一条日志就是在数组最前面插一个对象：

1
{
2
    version: "V1.1",
3
    title: "站内搜索",        // kind 徽章上的短语
4
    date: "2026-09-20",
5
    summary: "搜索页换了新引擎", // 卡片大标题，要短
6
    description: "把站内搜索换成了 Pagefind……", // 标题下的一段说明
7
    items: [
8
        { category: "首页", text: "具体改了什么" },
9
        { category: "性能", text: "又改了什么" },
10
    ],
11
    tags: ["搜索", "性能"],
12
}

字段逐个说一下：

加完保存，页面、统计卡（更新日数、记录条数、时间跨度）全部自动更新，不用改任何代码。

细节：从配置自动算统计#

源站的统计卡是写死的，我这里全部从配置实时算出来：

1
const totalItems = entries.reduce((sum, e) => sum + e.items.length, 0);
2
// 时间跨度：最早一条到最新一条，格式 26.09—26.09
3
const dateSpan = `${最早.date.slice(2, 7).replace("-", ".")}—${最新.date.slice(2, 7).replace("-", ".")}`;

当前版本取数组第一条、更新日数取数组长度、“第 N 次记录”倒着数。以后加日志，统计数字自己会涨，不用维护。

踩坑：两次跑错方向#

1. 概述不可信。第一版全靠文字描述，做出来四不像。第二次把 HTML 和 CSS 全部拉下来 1<1> 复刻才像样。教训：做界面参考，永远以源码为准，别信二手转述。
2. 菜单入口差点忘了。页面做完才反应过来——导航栏里根本没入口，访客怎么进？后来在「关于」子菜单里加了一项「博客日志」，放在「关于我」上面，顺手在关于页面里也补了个链接。日志页自己的返回按钮指向「关于我」，形成闭环。

写在最后#

这页做完，博客就算有了自己的”账本”。V1.0 已经把贴纸卡片那次的改动全记进去了，以后每折腾一次就记一条，看着版本号往上走，还挺有成就感的。

和贴纸一样，这次依然是三个新文件加两处内容文件的小改动，合并上游时零冲突。需要的人可以照这个思路给任何静态博客加日志页：路由靠文件约定，数据放配置，样式自包含。

页面地址：/blog-changelog/，导航栏「关于 → 博客日志」也能进。

一个前提：RSS 抓取发生在构建时#

先想清楚这事怎么做。老派的”朋友圈”是浏览器实时去抓别人的 RSS，要过一层 CORS 代理（rss2json 那套），又脆又慢，还依赖第三方服务活着。我的博客是纯静态，最顺的做法是反过来：抓取发生在 astro build 的时候，数据直接烤进 HTML，线上还是那个纯静态站点，服务器零参与。

代价也明确：内容的”新”取决于多久重新构建一次。所以我配了个 GitHub Actions 定时任务，每天自动抓一遍并提交快照，提交又触发 Pages 部署。每天更新一次朋友圈，对我来说完全够了。

核心代码：一个文件干完所有事#

抓取逻辑全在 src/utils/friends-feed.ts，页面入口 src/pages/moments.astro 里就一行关键代码：

1
const feed = await loadFriendsFeed(friends);

Astro 的 frontmatter 里顶层 await 是在构建时执行的，这一行就是”把全部友链的 RSS 抓回来”。

具体流程：

1. 遍历 friendsConfig.ts 里 enabled: true 的友链；
2. 每个站点按顺序猜 RSS 地址：先试你填的 rss 字段，没填就猜 rss.xml、feed.xml、feed/、atom.xml、index.xml 这些常见路径，还不行就抓首页解析 <link rel="alternate"> 标签；
3. 用正则把每个 feed 的 <item>/<entry> 拆出标题、链接、摘要、时间，每个站最多取 6 篇；
4. 所有来源去重、按时间倒序，合流成一条时间线。

防呆也做了：并发 5 个、单个 8 秒超时、失败重试 3 次。全部失败就用上一次的快照兜底，构建永远不会因为友链挂了而炸。

和友链共用一个配置#

朋友圈不是新数据源，它读的就是友链那一份配置。我给 FriendLink 类型加了一个可选字段：

1
// RSS/Atom 地址，可留空并由朋友圈页面自动探测
2
rss?: string | string[];

填了就优先用，不填靠探测。探测失败的站点会列在页面底部的提示里——“未订阅的站点：xxx”，方便你直接去跟对方要 RSS 地址。

顺带我还把自己也加进了友链：siteurl 指向本站、rss: "/rss.xml"，这样自己的文章也进时间线，页面上会打”本站主理人”的蓝色徽章（跟”推荐友链”的金色徽章区分开）。唯一的副作用是友链页也会出现自己这条，排在最前面当个自荐位，我觉得挺好。

每天自动刷新：一个 workflow 完事#

保持新鲜的方案是 src/data/friends-feed-snapshot.json 这个快照文件 + 一个定时 workflow：

1
# .github/workflows/refresh-friends-feed.yml（节选）
2
on:
3
  schedule:
4
    - cron: "30 1 * * *"  # UTC 01:30 = 北京时间 09:30
5
  workflow_dispatch:
6

7
permissions:
8
  contents: write

每天到点跑一遍 tsx scripts/refresh-friends-feed.ts，把抓到的结果写进快照文件并提交；提交触发 Pages 部署，朋友圈就连着快照一起更新了。抓取失败也没事，脚本不会报错，构建回退到旧快照，最多就是有一天没更新。

踩坑：两个加载不出来的头像#

这轮最折腾的反而不是抓取，是头像。

BlogsClub 的头像是对方站点的 favicon，浏览器里直接打开好好的，从我博客里加载就 404。排查了半天，用 curl 带不同 Referer 一个个试，发现它 nginx 按 Referer 做防盗链：从它自己站内点过去 200，从外部站点引过来 404。解决办法两层：友链页和朋友圈页的头像 <img> 全加 referrerpolicy="no-referrer"，同时把它的 favicon 下载下来本地托管（public/assets/images/friends/blogsclub-favicon.png），彻底不依赖对方服务器的心情。

我自己的头像也翻车了。profileConfig 里的头像是走 Astro 图片管线优化的，产物文件名带哈希（_astro/avatar.CjtmSIpt.avif），我手填的 /assets/images/avatar.avif 这个固定路径线上根本不存在。解决是复制一份到 public/ 目录——public 的文件原样进产物，路径不带哈希。

这两个坑都是构建/引用模型的特性，跟朋友圈本身没关系，但都是”看起来很简单，实际要绕一下”的典型。

改动清单：全部新增文件，不碰主题源码#

和之前的魔改一个规矩，方便以后合并 CuteLeaf/Firefly 上游：

改动之后我顺手做的调整：原来”社交”这个父菜单里塞着友链和留言，现在直接拆了，朋友圈、友链、留言都变成一级导航，首页导航栏一眼能看到朋友圈。

效果和一些数据#

当前 10 条启用的友链，8 个探测成功进了时间线（含我自己），46 篇文章合流，/moments/ 这页 HTML 约 550KB。这个体积只发生在朋友圈这一页，其他页面完全不受影响——首页、文章页该多快还多快，因为抓取是构建时的事，线上没有任何动态请求。

页面本身还带点小东西：顶部一张”随机一篇文章”的卡片，5 秒自动换一篇（可以关），配色和边框跟着主题走，深浅色都适配。朋友链文章多的时候有分页，每页 20 篇。

写在最后#

朋友圈这功能最打动我的地方是它把”友链”从一堆死链接变成了活的：谁更新了、什么时候更新的，一眼看过去就是整个圈子的近况。成本就一次构建多花个几十秒（每天定时任务跑，不占我手）——对静态博客来说，这买卖划算。

后面如果想再进一步，可以给每条时间线加”只看某个友链”的过滤，或者把快照改成增量只抓有变化的站。不急，先跑一阵子看看。

先扒站：仓库里根本没有这套代码#

第一反应是去仓库里找实现，结果 sticker、drag 全搜了一遍，啥都没有。它的 GitHub 仓库落后于线上站，这套装饰层根本没开源进去。

行吧，那就直接扒线上站。curl 把首页 HTML 拉下来，grep 一把 home-wallpaper-sticker，结构立刻清晰了：

1
curl -sL https://rainzt.cn/ -o rainzt.html
2
grep -o 'class="[^"]*sticker[^"]*"' rainzt.html | sort -u

从线上站一共拆出三块料：

1. 卡片 HTML：一个 article.home-wallpaper-card，头像、身份行、标题、副标题、导航、彩色标签，全是语义化标签
2. CSS：home-wallpaper-decor.css，22KB，从卡片毛玻璃到贴纸投影全带
3. JS：一段拖拽脚本，Pointer Events 实现，附带移动端四角随机投放和点击复制 toast

贴纸图片就直接从它站点上下载到自己的 public/images/home-stickers/，一共十几张 webp。

集成方案：全放新文件，只留一个挂载点#

这里我给自己加了个约束：以后要合并 CuteLeaf/Firefly 上游的更新。所以这套东西不能像传统魔改那样把主题文件改得到处都是，不然下次合并就是一场战争。

最终的结构是：

1
src/config/homeCardConfig.ts              # 新文件：全部配置
2
src/components/features/HomeWallpaperDecor.astro   # 新文件：HTML + CSS + JS 全自包含
3
public/images/home-stickers/              # 新目录：贴纸素材

主题文件只动了 WallpaperSection.astro 一个，改动是纯增量的一小段：

1
import HomeWallpaperDecor from "@/components/features/HomeWallpaperDecor.astro";
2
import { homeCardConfig } from "@/config/homeCardConfig";
3

4
const { state, backgroundImages, title, bannerPostMeta } = Astro.props;
5
const homeCardEnabled = homeCardConfig.enable === true;
6

7
{homeCardEnabled && <HomeWallpaperDecor />}

卡片上显示什么也全部收进配置文件，换标题、换社交链接、挪贴纸都不用碰组件：

1
export const homeCardConfig = {
2
  enable: true,
3
  identity: "HY",
4
  title: "折腾进行时",
5
  subtitle: "Hello, I'm HY.",
6
  navLinks: [
7
    { name: "文章", url: "/archive/" },
8
    { name: "友链", url: "/friends/" },
9
    // ...
10
  ],
11
  socials: [
12
    { name: "GitHub", icon: "fa7-brands:github", url: "https://github.com/hy4962" },
13
    { name: "Email，点击复制", icon: "fa7-solid:envelope", copy: "admin@9ll.uk" },
14
    // ...
15
  ],
16
  stickers: [
17
    // 具体使用时，每一项只需要管这五个值
18
    { src: "/images/home-stickers/blonde-idol.webp", name: "金发偶像", top: 20, left: 1.2, width: 112, rotate: 4 },
19
    { src: "/images/home-stickers/blue-witch.webp", name: "蓝发魔女", bottom: 5, left: 1.2, width: 98, rotate: -5 },
20
    // ...
21
  ],
22
};

以后合并上游，就算 WallpaperSection.astro 被改了，冲突也就几行，手工处理一下就完事。

使用指南：怎么改成自己的#

先说清楚数据流：配置文件只描述内容，组件负责渲染，主题只提供一个挂载点。日常改内容，你只需要动 homeCardConfig.ts 一个文件。

实现细节#

1
.home-wallpaper-decor {
2
  opacity: 0;
3
  visibility: hidden;
4
  /* ... */
5
}
6
html[data-wallpaper-mode="banner"] body.is-home .home-wallpaper-decor,
7
html[data-wallpaper-mode="fullscreen"] body.is-home .home-wallpaper-decor {
8
  opacity: 1;
9
  visibility: visible;
10
}

贴纸布局：从随手摆到强迫症对齐#

贴纸位置全用百分比，但默认值不能随便摆——卡片居中占了大约 34%~66% 的横向空间，导航链接和社交标签都在卡片下半部，贴纸直接压上去会挡住点击。

最终的布局结构是：左列（金发偶像上、蓝发魔女下）、右列（竹哒上、初音下）、底部中间一排三个。宽度用 min() 做响应式收缩：

1
width: min(105px, 5.4688vw, 11.5068vh);

中间排一开始我用 top 定位，结果贴纸身高不一，头顶齐了脚不齐，怎么看怎么别扭。后来把底部一排全改成 bottom 锚定——不管多高，脚都踩在同一条地面线上，瞬间工整了：

1
// bottom（距底）或 top（距顶）二选一
2
{ name: "蓝发魔女", bottom: 5, left: 1.2, width: 98, rotate: -5 },

踩坑记录#

这次踩的坑比写代码的时间还长，值得单独一节。

坑 1：默认横幅文字阴魂不散#

装饰卡片上线后，“World and Life” 那套默认横幅文字还叠在卡片上。我明明在服务端把 showHomeText 关了，HTML 里也确实带着 hidden 类——但页面跑起来之后它又出现了。

翻主题源码才发现有个 syncBannerHomeTextVisibility()，会在运行时按”是否首页 + 壁纸模式”重新计算并把 hidden 类摘掉。它不认识我的卡片，只知道”首页就该显示横幅文字”。

不想去改主题的工具函数，最后用同一条件的 CSS 规则直接压死：

1
html[data-wallpaper-mode="banner"] body.is-home .banner-home-text-overlay {
2
  display: none !important;
3
}

这段 CSS 在我的组件里，组件不渲染时它也不存在，卡片关掉就一切恢复原状。

1
.home-wallpaper-card { pointer-events: none; }
2
.home-wallpaper-card__nav a,
3
.home-wallpaper-card__social-link,
4
.home-wallpaper-card__avatar-sticker {
5
  pointer-events: auto;
6
}

坑 3：切到 fullscreen 模式，贴纸三连崩#

把壁纸模式切成 fullscreen 之后怪事来了：贴纸变大了一圈、下半截被裁掉、滚动一下还糊成一团。

查出来是主题在 fullscreen 模式下有针对壁纸容器内所有 img 的规则，一共三条变体，其中最高的一条长这样：

1
html[data-wallpaper-mode="fullscreen"][data-fullscreen-layout="classic"] #wallpaper-wrapper img {
2
  width: 100% !important;
3
  height: 100% !important;
4
  object-fit: cover !important;
5
  filter: blur(var(--fullscreen-blur)) !important;
6
  transform: scale(1.05) !important;
7
}

它的本意是让壁纸图铺满全屏、滚动时渐变模糊，但贴纸图也是 img，全被扫进去了：cover 负责裁切，scale(1.05) 负责放大，blur 负责糊脸，三个症状一次凑齐。

修法是在我自己的组件里加更高特异性的豁免规则。主题那条是 (1,2,2)，我借自己容器的类提到 (1,3,2)：

1
html[data-wallpaper-mode="fullscreen"] #wallpaper-wrapper .home-wallpaper-decor .home-wallpaper-sticker img {
2
  width: 100% !important;
3
  height: auto !important;
4
  object-fit: contain !important;
5
  filter: none !important;
6
  transform: none !important;
7
}

1
.home-wallpaper-card__avatar-sticker {
2
  transform: translate(var(--avatar-sticker-tx, 0px), var(--avatar-sticker-ty, 0px));
3
}

1
// fullscreen 下也照样能拖
2
sticker.style.setProperty("--avatar-sticker-tx", `${translateX}px`);
3
sticker.style.setProperty("--avatar-sticker-ty", `${translateY}px`);

坑 5：移动端随机投放，是我自己想当然#

一开始照搬参考站的移动端方案：只显示 4 张 mobile: true 的贴纸，随机投放到四块写死的百分比区域。结果上线一看不对劲——区域是死的，卡片却是活的，窄屏下卡片占掉九成宽，两块”侧边区域”直接压在卡片上，一张贴纸骑在社交标签上，另外三张干脆没显示。

想明白了就把”随机投放”整个删掉：移动端显示全部贴纸，布局和桌面端同一套结构，坐标由脚本按卡片实际边界换算——顶部两张贴在卡片上方，底部五个 bottom 锚定在卡片下方，中间三个在左右两列之间等分槽位。这样不管屏幕多窄都自适应。

1
cd public/images/home-stickers
2
for f in *.webp; do
3
  ffmpeg -y -loglevel error -i "$f" -vf "scale=192:-1" "tmp/$f"
4
done

效果#

手机端不再是另一套布局：和桌面端同一套结构，脚本按卡片实际位置自适应换算，便签自动居中到顶部：

拖拽是按下即拖，Pointer Events 鼠标触屏通用，位置限制在壁纸范围内，点击邮箱标签会弹”已复制”的 toast：

刷新后贴纸会回到初始位置，这点是故意的——位置记忆听着美好，但访客拖乱之后就再也回不去了，参考站也是这么做的。

极简流程#

1. curl 抓参考站 HTML，拿到卡片结构、CSS、拖拽 JS 三块料，贴纸图下载到 public/images/home-stickers/
2. 新建 src/config/homeCardConfig.ts，卡片内容和贴纸位置全配置化
3. 新建 src/components/features/HomeWallpaperDecor.astro，HTML/CSS/JS 自包含
4. WallpaperSection.astro 里加一个挂载点，同时把 showHomeText 短路掉
5. 显隐交给 body.is-home + data-wallpaper-mode 的 CSS 门控
6. 踩坑修复：压默认文字、放开卡片点击、fullscreen 豁免、CSS 变量拖拽、移动端自适应布局
7. 后续：换自己的贴纸素材、入场动画拆成文字/图片两段、关掉 Swup 视口预取

写在最后#

这次最值得记的其实不是贴纸本身，而是”合并友好”这个约束：所有逻辑收进两个新文件，主题只留一个挂载点，连踩坑修复都尽量用自己组件里的高优先级规则去覆盖，而不是直接改主题源码。以后上游更新合并过来，该是啥样还是啥样。

贴纸素材当时用的还是 rainzt 的演示图，后来换成了自己的一套角色（下面说）。想换成自己的图直接丢进 public/images/home-stickers/ 改下配置就行。

后续更新#

上面那一版是 9 月初的形态。后面又折腾了几轮，这里按时间补上，免得文章停在一个过时的状态。

1
@ 2614 ms  type=text  size=15194  nodeName=SPAN class='home-wallpaper-card__motion-text'

1
@keyframes home-wallpaper-title-enter {
2
  0% { opacity: 1; transform: translateY(12px); }
3
  to { opacity: 1; transform: translateY(0); }
4
}
5
.home-wallpaper-decor.is-ready .home-wallpaper-card h1 {
6
  animation-name: home-wallpaper-title-enter;
7
  animation-delay: 0.08s;
8
}

双栈是怎么来的#

一句话：边缘双栈，回源单栈。

家里宽带只有 IPv6，所以第一步是给 v6.xxx.com 配一条 AAAA 记录，ESA 回源的时候就顺着这条 IPv6 走。而访客那一侧连的是 ESA 边缘节点，ESA 边缘本身 IPv4、IPv6 都收，于是整条路就通成了：外面不管什么网络进来，先落到 ESA 节点，再由 ESA 用 IPv6 回你家。

这也是它和 CF 那篇共享的那套思路，唯一要记的就是：回源那条解析必须是 IPv6（AAAA），门面这层交给 ESA 去双栈。

第一步：Lucky 配一个阿里云 DDNS#

家里宽带有 IPv6，所以先让 Lucky 把家里的 IPv6 地址同步到域名上。DDNS 服务商选阿里云，域名假设叫 v6.xxx.com，类型 AAAA，IP 来源网卡 IPv6。

这步和之前 Cloudflare 那篇基本一样，就是服务商从 Cloudflare 换成阿里云，去 RAM 里建个 AccessKey 填进去就行。

第二步：Web 服务反代#

Lucky → Web 服务，添加反代规则：

• 监听端口：16666，后面 ESA 里回源也要全部指向 16666
• 前端：你的域名（比如 fnos.xxx.com）
• 后端：内网服务的地址（比如 http://192.168.31.31:8080）

第三步：两端配置证书（双自动续签，不用手动折腾）#

证书这块之前我踩了很大的坑，把事情搞复杂了，这里特地重新说一下。

1. Lucky 这边：ACME 自动申请#

在 Lucky 申请证书，添加方式选 ACME，颁发机构 Let’s Encrypt，验证方式选阿里云（填 AccessKey 就能自动过 DNS 验证）。

Lucky 本身申请的就是 Let’s Encrypt 证书，到期它自己会自动续签，压根不用人工干预。

2. ESA 这边：直接申请免费证书，也有自动续签#

我之前写的时候，以为 ESA 免费证书不能下载给 Lucky 用，而且在申请免费证书的时候发现输入框选不了一级域名，才觉得不行，于是大费周章地把 Lucky 里的证书下载出来，跑去 ESA 点“上传自定义证书”，还提醒大家以后记得手动来续签……

后来我才发现完全不用这么麻烦！阿里云 ESA 本身就可以直接申请免费证书，而且是平台自动签发、自动续期的！

之前之所以觉得选不了一级域名，是因为被阿里云控制台的交互给坑了：在「申请免费证书」的证书域名输入框里，它默认不会把一级域名弹出来，你必须手动把一级域名完整打全，下面才会弹出匹配选项供你勾选！

选好之后直接确定就行。

这样两头的证书就彻底顺了：

• Lucky 负责内网这一侧：自己走 ACME 自动申请并自动续期；
• 阿里云 ESA 负责外网边缘节点：平台免费证书自动签发并自动续期。

两边各自全自动闭环，谁也不用导谁的证书，以后再也不用担心证书过期要手动去更新了。

第四步：添加回源规则#

ESA → 规则 → 回源规则，新建一条：

• 匹配：所有传入请求
• 回源协议：跟随客户端
• HTTP 端口和 HTTPS 端口：都填 16666

第五步：ESA 域名解析 + DNS 的 CNAME 解析#

先在 ESA 里给站点添加记录，类型 CNAME，记录值指向第一步的 v6.xxx.com。

这里有个天大的坑：

回源 HOST 一定要选「跟随请求 HOST」！！！

回源 HOST 一定要选「跟随请求 HOST」！！！

回源 HOST 一定要选「跟随请求 HOST」！！！

否则 ESA 回源时带的 HOST 就不是你在 Lucky 里设置的那个前端域名，Lucky 收到请求压根不知道你要访问哪个服务，直接就 404 了。

然后去你 DNS 服务商那里，给要用的子域名加一条 CNAME，指向 ESA 分配的接入域名，完事。

可选：强制 HTTPS#

还在 SSL/TLS → 边缘证书页面，把「强制 HTTPS」开关打开，访客走 HTTP 也会被 301 到 HTTPS，建议开着。

和 Cloudflare 版怎么选#

两套流程几乎一模一样，差别就这几点：

国内访问多、手上又有备案域名，就选 ESA；只有个没备案的域名，或者想纯白嫖，就还是 CF 那套。原理完全一样，会了一套，另一套照着抄就行。

总结#

极简流程过一遍：

1. Lucky DDNS（阿里云）把 IPv6 同步到 v6.xxx.com
2. Lucky Web 服务反代，监听 16666
3. Lucky 与 ESA 各自配置免费证书（两端均全自动续签，别再手动上传了）
4. ESA 回源规则：所有请求，端口全部 16666
5. ESA 添加 CNAME 记录，回源 HOST 选跟随请求 HOST
6. DNS 服务商加 CNAME 指向 ESA 接入域名

两个坑记一下：

• 回源 HOST：不选「跟随请求 HOST」，Lucky 就认不出你要访问哪个服务，这条排查起来最费时间。
• ESA 免费证书：申请免费证书时必须手动打全一级域名才会弹出选项，选上就能自动签发续期；两端都自动更新，别再去手动下载上传证书了。

到这里整套就通了：外面用域名直接访问家里服务，ESA 国内节点加速，IPv4 和 IPv6 都能进，全程带 HTTPS。

其实有一个更加简单粗暴的办法，但是不符合我个人：组合优于继承 的理念..

直接把域名选择NS接入ESA，在lucky里面选择阿里云ESA的DDNS解析泛域名，然后在ESA将泛域名解析的代理状态打开

去配置回源16666，配置好两边的证书

回lucky反代各种服务即可

这个设置管什么用#

先说清楚，免得期望太高。Vercel 的静态资源（HTML、CSS、JS、图片）本来就走全球 CDN，访客从离自己近的节点拿，改不改都一样。受区域影响的只有 Serverless Functions——接口路由、SSR 页面、Middleware 这类需要真正跑代码的动态请求。

所以纯静态博客改了基本没感觉；但只要项目里有接口、SSR 或者评论后端这类动态请求，而访客又在亚太，那把区域改近一点就是有意义的。官方默认 iad1 的理由是大部分外部数据源（数据库之类）托管在美国东部，可对国内访客来说，这一来一回的延迟就不客气了。

怎么改#

操作不难，两分钟的事：

1. 打开 Vercel 控制台，进入要改的项目
2. 顶部切到 Settings，左侧选 Functions
3. 找到 Function Region 手风琴，展开后按大洲分组，勾一个离访客近的区域，比如亚太的香港 hkg1、东京 hnd1、新加坡 sin1、首尔 icn1
4. 右上角 Save 保存

注意面板里写着「A new Deployment is required for your changes to take effect」——改完区域必须重新部署一次才生效，光点保存没用。

踩坑记录#

1. Hobby 计划只能选 1 个区域。 默认北美组的华盛顿 iad1 是勾着的，你要是直接跑去亚太组再勾一个，就变成同时选中两个区域，Hobby 直接不允许。正确姿势是先把 iad1 的勾取消掉，再勾自己想要的区域，保证最后只剩一个。要是带着两个区域的配置去部署，会报 upgrade_required 的错，而且界面上就一句莫名其妙的 unexpected error，原因藏在部署记录里，挺坑的。
2. 改完要重新部署。 Save 之后记得去 Deployments 里 Redeploy 一次，不然设置改了跟没改一样。

   

要不要改#

我的判断：值得顺手改，但别期待逆天提升。

• 纯静态站点：改了没感觉，图个心理安慰
• 有 API / SSR / Middleware：值得改，动态请求少跑一趟美国
• 访客主要在国内：香港 ap-east-1 物理距离最近；要是数据库在别处（比如 Supabase 常用新加坡），就跟着数据源走

效果嘛，原作者的体感是有一点提升，但不是质变，属于「顺手改一下不亏」的级别。

极简流程#

1. 项目 → Settings → Functions → Function Region
2. 取消勾选默认的 iad1
3. 勾选一个离访客近的区域（如 hkg1）
4. Save → Redeploy

参考资料#

• 你的vercel项目，还能更快 - UpXuu’s blog
• Configuring regions for Vercel Functions - Vercel Docs

.eu.cc 免费域名活动是什么#

活动在 GNAME 官方活动页，核心就一句话：注册就送 .eu.cc 全额抵扣券，用券注册 0 元。

几个关键信息：

• 注册/登录 GNAME 账号后，每个账号能领 3 张全额抵扣券，一张券注册一个域名
• .eu.cc 正常价格 $12/年，用券 $0
• 想多领也有路子：官方给了代理名额，Basic Reseller 激活后 10 张，Advanced Reseller 共 20 张。激活条件我没深究，普通用户 3 个一般够用
• 转入也有活动价，页面标注低至 $1.88/年
• 活动页没写截止日期，想薅趁早

注册流程：领券、查询、0 元结算#

流程就四步：

1. 注册/登录 GNAME，打开活动页领取抵扣券
2. 搜索想要的域名
3. 结算时选全额抵扣券支付，$0 拿下
4. 要接 Cloudflare 的，注册完把 NS 改过去（下面单独说）

看着简单，但有两个坑，单独拎出来说。

踩坑记录#

托管到 Cloudflare#

GNAME 自己的 DNS 也能用（还带个免费的智能解析），但既然是折腾人，直接上 Cloudflare 白嫖全家桶。教程作者实测 .eu.cc 可以当正常域名托管，流程和普通域名一样：

1. Cloudflare 控制台 → Add a domain，填你的 xxx.eu.cc，选 Free 计划
2. Cloudflare 给出两个 NS 地址
3. 回 GNAME 的域名管理，把 DNS 服务器改成这两个 NS
4. 回 Cloudflare 触发检查，等生效（几分钟到几小时不等）

接上之后，之前写过的这几套玩法就都能搬过来了：

• Cloudflare+Resend域名邮箱：免费收域名邮箱，配 Resend 还能发
• CloudMail 无限收发邮箱：跑在 Workers 上的邮箱服务，收发一体
• Workers 部署一个免费图床：图床也吃 Cloudflare 这套，博客配图够用
• Cloudflare Tunnel Docker部署教程：不用公网 IP 把内网服务挂到公网
• 不用服务器自建节点：节点同样跑在 CF Pages 上，免费白嫖
• IPv6 + Lucky 白嫖双栈 HTTPS：那篇的前提就是”一个托管在 Cloudflare 的域名”，现在域名有了

适合谁，我的判断#

• 适合：博客、导航站、个人主页、在线工具、项目展示页、短链接站、测试站。反正 0 成本，试错随便试，试错了就扔
• 和 eu.org 比：域名短得多，领券直接注册，不用等审核
• 不适合：正经长期项目。免费活动随时可能调整，二级域的”根”也不在自己手里，长期项目还是买个正规付费顶级域名踏实

我的判断：拿来折腾是真的香。但”0 元”的前提是记得去活动页续费——这个活动最大的成本不是钱，是记性。

极简流程#

1. 注册/登录 GNAME → 活动页领 3 张全额券（30 天内用掉）
2. 搜域名，避开两字母、三字母、品牌词等溢价域名
3. 结算用券，$0 注册
4. 到期前 90 天：活动页 Renew for free 列表里免费续费，别碰”我的域名”里的续费和自动续费
5. 要接 Cloudflare：Add a domain → 改 NS → 等生效

起因：想给 DSH 搬家#

Windows 上的 DSH 存在 C:\Users\XOS\.dsh 里，结构大概是：

• profiles/web/：web 版 profile，插件清单（package.json）、启用配置（cordis.yml）、依赖都在这
• settings.yaml：全局配置，模型、皮肤、面板开关之类
• .credentials.yaml：API key 等凭据
• 各个插件自己的数据目录，dsh-bill/、dsh-chat-import/、skin-center/……

我最初的想法很直接：整个 .dsh 拷到 NAS 挂载进容器，完事。结果第一步就栽了。

坑一：Junction 变成了实体目录#

先在 Windows 上 robocopy 把 .dsh 备份出来，然后整个丢进容器的挂载目录，启动容器：

1
Error: dsh: /root/.dsh/profiles/node_modules/@deepseek-ai/dsh exists
2
and is not a symlink; remove it so dsh can manage the installation fallback

当时人直接傻了：@deepseek-ai/dsh 怎么会「存在但不是符号链接」？

原因很阴：Windows 上 DSH 核心包的 node_modules 全是 Junction（目录符号链接），真正的实体在 D:\.pnpm-store。我 robocopy 的时候没加 /XJ，这些链接就被解析成实体目录拷了过去。到 Linux 上一看，DSH 期望这里是个干净的 symlink 好自己管理，结果是个实打实的目录，直接罢工。

坑二：依赖没装，DSH 拒绝启动#

删掉坏东西重来，把干净的备份（34MB，无 node_modules）传到 NAS 挂载目录。启动，又崩：

1
Error: dsh: cannot resolve profile bundle "dshmarket" from the dsh
2
installation or /root/.dsh/profiles/web; run 'dsh plugin --profile web
3
install' if its dependency is not installed

这个好懂：node_modules 没带过来，DSH 也不会自己装，得进容器跑 pnpm install。麻烦的是容器一启动就崩，根本进不去，docker exec 无从谈起。

AI 给的办法很骚：用一次性容器，同一个镜像、同一个挂载，覆盖启动命令直接进 shell 装依赖：

1
docker run --rm \
2
  -v /vol1/1000/Docker/DSH:/root \
3
  --entrypoint /bin/bash \
4
  smanx/deepseek-harness:devtools-latest \
5
  -c "cd /root/.dsh/profiles/web && pnpm install --prod --frozen-lockfile"

web profile 装完再补 dsh-tui 那个 profile，同一个套路：cd /root/.dsh/profiles/dsh-tui && pnpm install --prod --frozen-lockfile。

关键点就三个：--rm 用完即毁，--entrypoint /bin/bash 跳过正常启动命令直接给 shell，-v 挂载同一个数据卷。等于在容器外面修容器里面的世界，那个崩掉的容器根本不用管。装完确认插件都回来了：dshmarket、dsh-bill、dsh-vision-router、@nanmicoder/dsh-agent-teams，一个不少。

坑三：凭据文件权限 666，安全校验拦路#

依赖齐了，启动，还炸：

1
credentials-local: /root/.dsh/.credentials.yaml is readable beyond its
2
owner (mode 666); run "chmod 600 /root/.dsh/.credentials.yaml" before
3
starting again

这是 Windows 拷文件的经典后遗症：robocopy 备份时把文件权限全放开了，.credentials.yaml 成了 666，谁都能读。DSH 有安全校验，凭据文件必须属主独占。

1
chmod 600 /root/.dsh/.credentials.yaml

顺手把 settings.yaml、dsh-ssh.json 也一起收紧。

坑四：TUI 插件要 TTY，后台容器没有#

第四次启动，日志里终于不是「启动即退」了，但还是起不来：

1
Error: dsh-tui requires an interactive terminal (stdout must be a TTY).

原因是我的 profile 里启用了 @deepseek-harness-tui/dsh-tui（TUI 界面插件）。它启动时会检测 stdout 是不是 TTY，容器里 dsh web & 是后台跑，没有 TTY，直接抛异常。

解法也简单：web 部署反正用浏览器访问，TUI 用不上，直接在 profile 的补丁配置里禁掉。在 cordis.patch.yml 追两行：

1
# Docker 后台部署无 TTY，禁用 TUI（web 浏览器访问不受影响）
2
- id: dsh-tui
3
  disabled: true

修好了：容器平稳运行#

四次折腾完，容器终于 Up 起来了：

1
[dsh] DSH 就绪（pid 7）
2
[proxy] 启动代理：0.0.0.0:3080 -> 127.0.0.1:3079

端口探活直接 HTTP 200，浏览器打开就是熟悉的 DeepSeek Harness 界面。插件、配置、聊天记录全都在，等于搬了个家，行李一件没丢。

AI 全自动修复是怎么做到的#

说回重点。整个过程里，AI（就我正在用的这个 agent）做的不是「丢几条命令让你自己跑」，而是全程接管：

1. 远程连宿主机：直接 SSH 到 NAS，docker ps -a 看容器状态，docker inspect 确认挂载关系
2. 判断挂载点：一眼看出 -v /vol1/1000/Docker/DSH:/root 意味着整个根目录都在宿主机上，所以「不进容器也能修」
3. 改文件用 sudo 提权：宿主机上 .dsh 属主是 root，AI 自己拿 root 密码提权读写
4. 自动打包传输：本地 tar -czf 打包备份，ssh_upload 传过去，远端解压，再校验文件都在
5. 自我纠错：每修一步就启动一次容器、读日志、分析下一个报错，然后接着修，四个坑全是这么被逐个填平的
6. 顺手清理：tar 包、一次性容器，用完都收拾干净

全程我给它的指令大概就两三条：「拷过去报错了」「容器进不去怎么办」「现在好了吗」。剩下全是它自己来。最爽的是它自己就注意到备份里没有 node_modules、注意到权限是 666、注意到 TUI 要 TTY，每个都是看一眼报错日志就定位到根因，然后给出对应修法。

以前遇到这种「启动即崩、日志一大坨」的容器问题，我的流程是：搜报错，复制一堆命令，越改越乱，最后重装。这次基本是它修、我看，体验完全不一样。

经验总结#

这套流程以后再遇到同类场景可以直接抄：

1. 备份 .dsh 时排除 node_modules 和 junction（/XJ /XD node_modules）
2. 清单文件（package.json、pnpm-lock.yaml、cordis.yml）必须带，这是重建依赖的依据
3. 到新机器后手动跑一次 pnpm install --prod --frozen-lockfile，别指望 DSH 自动装
4. 迁完用 chmod 600 收紧 .credentials.yaml 等敏感文件
5. Docker 或后台部署记得禁用 TUI 类插件（cordis.patch.yml 里 disabled: true）
6. 容器崩了进不去？用一次性容器 + 同挂载覆盖 entrypoint，在容器外面修

最值钱的一条还是那句：跨平台迁移，别硬搬 node_modules。让依赖在目标环境重新装，比带着一堆 Windows 链接结构过去折腾省事得多。

写在最后#

这次折腾给我最大的感受倒不是 DSH 迁成功了，而是「AI 全自动运维」这状态离日常生活真不远了。一个能 SSH、能判断挂载关系、能自己打补丁重启再验证的 agent，处理这种环境迁移问题已经挺能打。当然它也不是万能的，中间好几次我都怀疑它要卡住了，结果它就是硬生生把四个坑一个个填平。

先说结论：官方目前没有 Docker 版#

官方仓库的 README 里只写了两种用法：npm 装（npx @deepseek-ai/dsh web 起 Web UI）和源码编译，一个字没提容器。项目还在 developer preview 阶段，官方也明说后续会有破坏性变更。

更麻烦的是，dsh web 出于安全考虑只监听 127.0.0.1:3080，--host 0.0.0.0 是被禁止的。这意味着就算你自己把 npm 包塞进容器，局域网里其他设备照样连不上，还得自己套一层反代。

社区镜像就是冲着这两个问题去的。

方案一：smanx/deepseek-harness — 内置反代，开箱即用#

官方讨论区 #1762 里 smanx 打包的镜像，Docker Hub 和 GHCR 双仓库（ghcr.io/smanx/deepseek-harness，tag 一致）。

镜像内置一个 Node 反向代理：监听 0.0.0.0:3080 转发到容器内的 127.0.0.1:3079，顺手解决了三件事：

• WebSocket 转发（/api/events.mux、/api/events.host），不然网页端消息推不出来；
• 局域网 IP 属于非安全上下文，crypto.randomUUID 不可用，反代会往 HTML 里注入 polyfill，否则连接一直 pending；
• 可选的 HTTP Basic Auth。

tag 有三档，按需选：

启动命令（原帖原文）：

1
docker run -d \
2
  --name dsh-harness \
3
  -p 3080:3080 \
4
  -v dsh-data:/root/.dsh \
5
  --restart unless-stopped \
6
  smanx/deepseek-harness:latest

可用的环境变量：

• DSH_PORT：dsh web 端口，默认 3079
• PROXY_PORT：反代端口，默认 3080
• PROXY_USERNAME / PROXY_PASSWORD：两个都设置才启用 Basic Auth

评论区还有人给了 compose 版，把代码目录也挂进去：

1
services:
2
  dsh-harness:
3
    image: smanx/deepseek-harness:devtools-latest
4
    container_name: dsh-harness
5
    ports:
6
      - "3080:3080"
7
    volumes:
8
      - /home/ly/code:/home/ly/code   # ⚠️ 改成你的代码目录
9
      - /home/ly/.dsh-home:/root      # ⚠️ 改成你的持久化目录
10
    restart: unless-stopped

方案二：runzhliu/deepseek-harness — 安全加固，带 K8s 参考#

runzhliu 的版本（对应 0.1.1-rc.2，构建参数可换）走的是另一个思路：不碰 0.0.0.0，端口只绑 127.0.0.1，要访问就 SSH 隧道或 kubectl port-forward。安全细节给得挺足：非 root（UID 1000）运行、只读根文件系统、drop ALL capabilities、no-new-privileges、tini 收尸。额外还带了个 noVNC 浏览器桌面（6080 端口），网页里能直接看到容器桌面。

1
docker run --rm --name deepseek-harness \
2
  --publish 127.0.0.1:3080:3080 \
3
  --publish 127.0.0.1:6080:6080 \
4
  --shm-size 1g \
5
  --mount type=volume,src=dsh-home,dst=/home/node/.dsh \
6
  --mount type=bind,src="$PWD",dst=/workspace \
7
  runzhliu/deepseek-harness:0.1.1-rc.2

compose 用法是 docker compose pull 之后 DSH_WORKSPACE=/绝对路径 docker compose up -d。注意工作区目录必须对 UID 1000 可写，否则直接 EACCES。K8s 那边给了单副本 StatefulSet + NetworkPolicy，默认拒绝入站——作者很克制，明确不建议当 HA 扩容用。另有一个预装 dshmarket 的 market 变体（tag 0.1.1-rc.2-market.1），要用 compose.market.yaml 显式启用。

怎么选#

我的判断：NAS 或家里服务器想给全设备用，smanx 顺手得多，记得把 Basic Auth 打开；runzhliu 适合自己一个人用、对安全默认值有要求的场景，K8s 部署直接抄它的配置。

踩坑记录：本机 0.1.1-rc.2 的 peer 依赖炸弹#

回到开头那个报错。Cannot find package '@deepseek-ai/cordis-plugin-group'，排查下来不是我的问题，是这版打包的锅：19 个内部包（dsh-invariants、dsh-sandbox、dsh-timeout……）只被声明成 peerDependencies，但没有任何包实际安装它们，其中 dsh-invariants 被 168 处引用，等于大半个 dsh 都等着它。

解决办法是把缺的包补装进全局包自己的 node_modules（npm install --no-save 指着缺失清单装就行），补完 dsh --version 立刻活过来。顺手还修了一个插件的 MCP 路径解析问题，这里不展开。

所以如果你自己装 rc.2 也碰到同样的报错，先怀疑依赖没装齐，别急着删配置。社区镜像万一也踩到，docker exec 进容器补依赖，思路一样。

部署前的几个注意#

1. 持久化：容器内的 .dsh 目录（配置、会话、凭据）一定要挂卷，工作区用 bind mount；反过来，别把 ~/.ssh、云凭据、docker socket 挂进容器。
2. API Key：headless 运行用 DEEPSEEK_API_KEY 环境变量注入，不要写进镜像层。
3. 架构：拉取前确认镜像架构和你的设备匹配（NAS 有 x86 也有 arm）。
4. Windows 本机想跑 Docker 版需要 Docker Desktop（WSL2），我这种本来就有服务器/NAS 的，直接部署到远端更省心。

接下来打算#

上面这些命令都来自原帖和项目 README，我还没实机跑过——等我把它在 NAS 上用 devtools-latest + Basic Auth 跑起来，再写个实测续篇。

写于 2026 年 8 月，折腾 dsh 的记录。

图片建议#

• 位置：文章开头或方案一节，容器跑起来后浏览器访问 http://NAS的IP:3080 的 Web UI 界面截图
• 位置：踩坑记录一节，ERR_MODULE_NOT_FOUND 的终端报错截图
• 作用：封面 + 证明服务真的跑起来了 / 报错现场
• 推荐尺寸：封面 1200×630，正文图宽度不超过 1600

为什么选 OpenViking#

OpenViking 干的事：给 Agent 一个统一的、可检索的长期记忆库。

• 记忆、资源、技能统一用 viking:// URI 管理，像操作文件系统一样 ls、find，不是黑盒向量库
• 内容写进去时自动分级处理：L0 摘要（约 100 token）、L1 概览（约 2k token）、L2 全文，按需加载，省 token
• 检索是可观测的，能看它是沿哪条路径找到结果的
• 会话结束后自动从对话里提取偏好和经验写进长期记忆

选择在 NAS 自托管而不是用云服务，就一个理由：数据在自己手里。记忆这种东西我不想放别人服务器上。OpenViking 官方自己也要求 Docker 部署时数据全在挂载目录里，天然适合 NAS。

准备工作#

• fnOS 一台（x86_64），Docker 和 Docker Compose 可用（我这边 Docker 29.7.2 / Compose v5.5.0）
• 用 SSH 登录 NAS（fnOS 的 hy4962 用户在 docker 组，可以直接跑 docker 命令）
• 两个模型服务：
  • Embedding（向量化）：我用 SiliconFlow 的 Qwen/Qwen3-Embedding-4B（原因见下）
  • VLM（内容理解/摘要）：走我自己搭的 new-api 网关（OpenAI 兼容），模型 deepseek-v4-flash

第一步：数据目录#

部署之前先把目录结构定好，这是后面迁移最省心的一步。OpenViking 容器内所有持久状态都在 /app/.openviking 这一个目录下（配置 + workspace 数据全在里面），所以直接把 NAS 上的目录整个挂进去：

1
/vol1/1000/Docker/OpenViking/
2
├── ov.conf            # 配置（模型、存储、root key）
3
├── docker-compose.yml
4
├── data/              # workspace：文件库 + 向量库 + bot
5
└── cache/             # 模型缓存

以后换机器迁移，把这个目录整个拷走就行，数据配置模型一个不落。镜像本体在 Docker 存储里，不占这个目录。

第二步：ov.conf 和 docker-compose#

先写 ov.conf。关键三件事：server.root_api_key（容器内绑定 0.0.0.0 时必须有，否则拒绝启动）、embedding、VLM：

1
{
2
  "server": {
3
    "host": "0.0.0.0",
4
    "port": 1933,
5
    "root_api_key": "换成你自己的随机串",
6
    "cors_origins": ["*"]
7
  },
8
  "embedding": {
9
    "dense": {
10
      "provider": "openai",
11
      "model": "Qwen/Qwen3-Embedding-4B",
12
      "api_base": "https://api.siliconflow.cn/v1",
13
      "api_key": "你的 SiliconFlow key",
14
      "dimension": 2560
15
    }
16
  },
17
  "vlm": {
18
    "provider": "openai",
19
    "model": "deepseek-v4-flash",
20
    "api_base": "http://192.168.31.3:3000/v1",
21
    "api_key": "你的 new-api key"
22
  },
23
  "storage": {
24
    "workspace": "/app/.openviking/data",
25
    "agfs": { "backend": "local" },
26
    "vectordb": { "backend": "local" }
27
  }
28
}

docker-compose.yml 就一行挂载的事：

1
services:
2
  openviking:
3
    image: ghcr.io/volcengine/openviking:latest
4
    container_name: openviking
5
    restart: unless-stopped
6
    ports:
7
      - "1933:1933"
8
    volumes:
9
      - /vol1/1000/Docker/OpenViking:/app/.openviking
10
    environment:
11
      - TZ=Asia/Shanghai

踩坑记录：换 embedding 模型，服务直接拒绝启动#

这是最大的一个坑。

Embedding 模型决定向量库的坐标系，所有记忆的向量都按它生成。换模型 = 换坐标系，所以向量库必须”一个模型一个池子”。OpenViking 启动时会校验向量库记录的 embedding 元数据和当前配置是否一致，不一致直接拒绝启动，这是保护机制：

1
EmbeddingRebuildRequiredError: Existing collection embedding metadata does
2
not match current configuration. Rebuild is required...

我一开始用的 Qwen3-Embedding-0.6B（1024 维），后来想换 4B，改了配置重启，就撞上这个。而且更关键的是：

维度都变了，不是同一个坐标系的问题，是盒子尺寸都不一样了，旧向量完全没法复用。处理方式：

1. 停容器，删掉旧向量库（data/vectordb/context，备份一份再删）
2. 改 ov.conf 里 dimension: 2560
3. 启动，向量库按新模型重建
4. 已有内容重新向量化（我直接重新导入一次，173 个文件，210 秒跑完，零错误）

如果你换的是同维度的模型（比如 4B ↔ 8B，都是 2560），理论上可以设 embedding.allow_metadata_override: true 保留旧向量，但不建议，不同模型的语义空间不同，新旧向量混在一个库里检索会失真。老老实实重建最干净。

账号和权限：一个 Agent 一个用户#

OpenViking 是多租户的：account（工作区）+ user（用户）。记忆、会话按用户隔离，viking://resources 是同一工作区共享的。

实践建议：每个 Agent 一个 user 账号，各自用各自的 user key 连接，记忆互不干扰。创建用户走 Admin API（root key 调用）：

1
curl -X POST http://127.0.0.1:1933/api/v1/admin/accounts/default/users \
2
  -H "Content-Type: application/json" \
3
  -H "X-API-Key: <root-key>" \
4
  -d '{"user_id": "hermes", "role": "user"}'
5
# 返回 user_key，就是给这个 agent 用的

注意三种角色的分工：

root key 不能直接访问数据 API（返回 PERMISSION_DENIED），Agent 连接必须用 user key。

部署完成长什么样#

启动后等健康检查通过：

1
curl http://127.0.0.1:1933/health
2
# {"status":"ok","healthy":true,...}

浏览器打开 http://你的NAS-IP:1933/studio 就是 Web Studio：

给 agent 配连接时就是填这个地址 + user key。我的 Hermes 打开 OpenViking 记忆提供方配置页，ENDPOINT 填 http://192.168.31.3:1933，API KEY 填 hermes 用户的 user key，保存即可。

延伸：把 Hindsight 的记忆迁过来#

我之前用 Hindsight 给 Hermes 当记忆库，里面 570 条记忆单元 + 16 个会话全文。迁移路径是 Hindsight API 只读导出 → 转成 markdown → OpenViking 官方 API 导入，不是复制数据库文件（两家存储格式完全不兼容，Hindsight 是 PostgreSQL 图结构，OpenViking 是文件系统 + 向量库）。

导出（Hindsight 8888 端口 API）：

1
curl "http://127.0.0.1:8888/v1/default/banks/hermes/memories/list?limit=100&offset=0"

组装成 markdown（一条记忆一个标题块，保留时间/实体/来源），打包上传导入：

1
curl -X POST http://127.0.0.1:1933/api/v1/resources/temp_upload \
2
  -H "X-API-Key: <user-key>" -F "file=@hermes-hindsight.zip"
3
curl -X POST http://127.0.0.1:1933/api/v1/resources \
4
  -H "Content-Type: application/json" -H "X-API-Key: <user-key>" \
5
  -d '{"temp_file_id": "...", "to": "viking://user/hermes/resources/hindsight-import"}'

导入后 OpenViking 自动向量化 + 生成摘要，中文语义检索实测命中率不错（“欧盟人工智能法案”这类查询能稳定召回）。要说损失也有：Hindsight 的知识图谱关系边没法迁移，记忆从”图结构”变成了”可语义检索的资源库”，这是迁移的本质，不是意外丢失。

极简流程#

1. 建目录 /vol1/1000/Docker/OpenViking，写 ov.conf（root key + embedding + VLM）
2. docker compose up -d，等 /health 返回 ok
3. 客户端连接：http://NAS-IP:1933 + 一个 user key（Admin API 创建）
4. 换 embedding 模型 = 重建索引，换 VLM = 随便换

写在最后#

OpenViking 是我目前用下来最顺手的 agent 记忆方案：开源、本地数据、多租户隔离，Web Studio 能直接看记忆结构。折腾下来最大的坑就是向量模型那个，其余都挺顺的。数据全部落在 /vol1/1000/Docker/OpenViking，哪天要换机器，整个目录拷走 + docker save 镜像就完事。

准备工作#

• 一台部署了 Lucky 的设备。安装过程就不展开了，教程一大把，实在太简单。连安装都搞不定的，下面的配置估计也够呛，不如直接用付费的内网穿透工具，省心。
• 一个托管在 Cloudflare 的域名，Free 套餐就行（我的是 547466.xyz）。

第一步：Lucky 添加 IPv6 DDNS#

打开 Lucky → 动态域名，添加一个 DDNS 任务：

• 服务商选 Cloudflare，填上你的域名和 API Token
• IPv6 地址来源选 网卡（ipv6Addr）
• 域名记录里把要用的域名配上，类型 AAAA（我是指向内网飞牛那台机器的）

任务开起来之后，去 Cloudflare 看一眼解析记录，确认已经同步过去。

第二步：Cloudflare 开代理，SSL 先设灵活#

关键一步：每条 DNS 记录旁边的「代理状态」必须开着（橙色云），不然下面说的规则全都不生效。我这边 AAAA 记录都是已代理状态。

然后 SSL/TLS → 配置加密模式，先选「灵活」。这样访客到 Cloudflare 这段是 HTTPS，Cloudflare 到源站暂时走明文，先把链路跑通。想全链路 HTTPS 的话后面有专门一节。

第三步：添加 Origin Rule，把端口去掉#

这是整套方案的核心。Cloudflare 对外只开放 80/443，我用一条 Origin Rules（源站规则） 把所有入站请求的目标端口重写成 Lucky 的监听端口，这样外面访问 https://你的域名 就够了，不用再记端口。

操作路径：规则 → 概览 → Origin Rules，添加规则：

• 匹配条件：所有传入请求
• 操作：目标端口 → 重写到 16666

第四步：Lucky 添加 Web 服务#

回到 Lucky → Web 服务，添加规则：

• 监听类型勾上 IPv6
• 监听端口 16666，必须跟上面 Origin Rule 重写的端口保持一致

规则下面可以加子规则，前端地址填想要的域名，后端地址填内网实际地址。我这边挂了两个服务：

到这一步，不带端口号访问已经通了。剩下的是可选强化。

（可选）全链路 HTTPS#

默认「灵活」模式下，Cloudflare 到源站这一截是明文。想两头都加密，按下面来：

1. 加密模式改回「完整（严格）」：SSL/TLS → 配置加密模式，选「完整（严格）」，它会验证源站证书。

1. 创建源站证书：SSL/TLS → 源服务器 → Origin 证书，创建一张 Cloudflare 签发的免费源站证书（选你要加密的域名就行）。

3.把证书存成 txt：生成后页面上有「源证书」和「私钥」两段 PEM 内容，分别复制保存成两个文件（我存的是 yuan.txt 和 key.txt）。

1. Lucky 上传证书：Lucky → SSL/TLS 证书 → 添加证书，方式选「文件」，证书选 yuan.txt，Key 选 key.txt。

   

2. Web 服务开启 TLS：回到 Web 服务那条规则，把 TLS 打开（最低版本 TLS1.2）

   

这样就是全链路 HTTPS：浏览器 → Cloudflare（CF 泛域名证书）→ 源站（Origin 证书）。

lucky里面也可以直接申请Let’s Encrypt的证书，那个也行。加了证书之后，⚠️访问一定记得要带https！

极简流程#

1. Lucky 添加 DDNS：网卡取 IPv6 → 同步到 Cloudflare 的 AAAA 记录（开代理）
2. Cloudflare 加密模式先设「灵活」
3. Cloudflare 添加 Origin Rule：所有请求目标端口重写到 16666
4. Lucky Web 服务：监听 16666，子规则按域名反代到内网
5. （可选）CF 改「完整（严格）」+ Origin 证书 + Lucky 开 TLS → 全链路 HTTPS

准备工作#

就三样：

1. 一个 Cloudflare 账号（免费版就行）
2. 项目安装包：去 edgetunnel 仓库下载 main.zip，顺手给作者点个 Star
3. （可选）一个自己已有的域名，已经托管到 Cloudflare 的最省事

第一步：创建 Pages 项目并部署#

进 Cloudflare 控制台，左侧找到 Workers 和 Pages，在创建页面的最底部有一行「想要部署 Pages？开始使用」，从这里进：

Pages 项目不用连 GitHub，选 上传资产 的方式就行。给项目取个名字，点击 创建项目，然后把刚才下载的 main.zip 拖进去上传，右下角点 部署站点：

等进度条跑完，首次部署就成了。

第二步：设置管理员密码，再重新部署#

这一步是最容易漏的。部署完先别急着访问，要先告诉它管理员密码是多少：

1. 点 继续处理站点 进入项目
2. 设置 > 环境变量 > 为生产环境定义变量 > 添加变量
3. 变量名称填 ADMIN，值填你自己定的管理密码，点 保存

保存之后环境变量不会立即生效，回到 部署 选项卡，右下角点 创建新部署，把 main.zip 再传一遍，点 保存并部署。后面每改一次配置都要这么重新部署一次，记住这个套路。

第三步：创建 KV 命名空间并绑定#

edgetunnel 需要一个 KV 来存配置数据，不然后台很多东西没法持久化。

先建空间：在左侧菜单找到 存储和数据库 > Workers KV，点右上角 Create Instance，弹窗里给命名空间起个名字，随意：

建好之后就能在列表里看到它了：

然后绑定到 Pages 项目：打开项目 设置 选项卡，往下找到 绑定，点 + 添加，在弹窗里选 KV 命名空间：

关键的地方来了：变量名称必须填 KV（大小写一致），KV 命名空间选刚才建的那个，点 保存：

弹窗里会提示”此更改将在下次部署时生效”，所以老规矩，回部署页面再重新部署一次。

第四步：绑定自定义域名（可选）#

不绑域名也能用自带的 xxx.pages.dev 访问，但部分地区 DNS 污染严重，pages.dev 域名根本打不开，所以有自己的域名建议还是绑一下：

1. 在 Pages 控制台切到 自定义域 选项卡，点 设置自定义域
2. 填入你的次级域名。注意别拿根域名来用，比如你的根域名是 example.com，这里就填 cf.example.com 这种
3. 按提示回域名的 DNS 服务商那里，添加一条 CNAME 记录：主机记录 cf，指向 edgetunnel.pages.dev，然后点 激活域

配置没问题的话证书会自动签发，几分钟就能生效。视频版可以看这个视频教程。

第五步：进入后台#

浏览器访问 https://你的域名/admin（没绑域名就用 https://项目名.pages.dev/admin），输入第二步设置的 ADMIN 密码就能登录。后台长这样：

上面就是节点链接和订阅地址，复制到 v2rayNG、Clash Verge 这类客户端导入就能用了，软路由上跑 OpenClash 的话订阅直接导进去，全家设备都能走。右上角还有个”我是高手！我就是要折腾！“的入口，想玩优选 IP、ProxyIP、订阅转换的可以从那里深入，我目前还没折腾到那一步——优选 IP 单独写过一篇：Cloudflare Workers优选IP。

踩坑与提醒#

1. 改了配置不生效：ADMIN 环境变量、KV 绑定都是下次部署才生效，改完必须重新上传 zip 部署一次
2. KV 变量名称：必须一字不差地填 KV，不是随便起的名字
3. 自定义域名别用根域名：根域名留给解析，节点用次级域名就行
4. 免费额度对个人轻度使用完全够，但别拿来做重活，毕竟吃的是 CF 的公益饭

极简流程#

1. 下载 main.zip
2. Pages 上传资产部署，设 ADMIN 环境变量，重新部署
3. 建 KV 命名空间，绑定到 Pages，变量名 KV，再重新部署
4. （可选）绑个自己的次级域名
5. 访问 /admin 登录，复制订阅到客户端

参考资料#

• Edgetunnel 2.0 全新版本 - CMLiussss Blog
• 2026 最强 Cloudflare 免费节点 - 零度博客

三件套都是什么#

整套东西就是三个容器：

原理上 NapCat 把 QQ 账号包装成一个 OneBot 协议服务，MaiMBot 通过正向 WebSocket 连上去，就能收发群消息了。所以核心就两步：NapCat 登录 QQ 并监听，MaiMBot 连上这个监听端口。

编写 docker-compose.yml#

我直接用项目提供的示例，稍微整理了一下。完整文件如下：

1
services:
2
  core:
3
    container_name: maim-bot-core
4
    #### prod ####
5
    image: sengokucola/maibot:latest
6
    # image: infinitycat/maibot:latest
7
    #### dev ####
8
    # image: sengokucola/maibot:dev
9
    # image: infinitycat/maibot:dev
10
    environment:
11
      - TZ=Asia/Shanghai
12
      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656
13
      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0
14
      - MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED=1 # Docker 无法交互确认旧版升级迁移，默认跳过确认提示
15
      - MAIBOT_STATISTICS_REPORT_PATH=/MaiMBot/data/maibot_statistics.html # 统计数据输出到共享目录，首次运行可自动创建文件
16
      - WEBUI_HOST=0.0.0.0 # Docker 中需要监听全部容器网卡，宿主机才能通过端口映射访问 WebUI
17
    #      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656 # 同意EULA
18
    #      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0 # 同意隐私条款
19
    ports:
20
      - "18001:8001" # webui端口
21

22
#      - "8000:8000"
23

24
    volumes:
25
      # 监听地址和端口会用于生成或迁移 ./docker-config/mmc/bot_config.toml 的 maim_message 与 webui 配置段
26
      - ./docker-config/mmc:/MaiMBot/config # 持久化bot配置文件
27
      - ./data/MaiMBot:/MaiMBot/data # 共享目录
28
      - ./data/MaiMBot-plugin-data:/MaiMBot/data/plugins # 插件持久数据目录，与插件源码目录隔离
29
      - ./data/MaiMBot/emoji:/data/emoji # 持久化表情包
30
      - ./data/MaiMBot/plugins:/MaiMBot/plugins # 插件目录
31
      - ./data/MaiMBot/logs:/MaiMBot/logs # 日志目录
32
      - ./depends-data:/MaiMBot/depends-data # 运行时资源文件
33
      # - site-packages:/usr/local/lib/python3.13/site-packages # 持久化Python包，需要时启用
34
    restart: always
35
    networks:
36
      - maim_bot
37

38
  # 启用 HTTPS 时，建议注释掉 core 服务中的 "18001:8001" 端口映射，
39
  # 然后取消注释此 Caddy 反向代理示例块，并按 dashboard/docs/Caddyfile.docker.example 修改域名。
40
  # caddy:
41
  #   image: caddy:2
42
  #   container_name: maibot-caddy
43
  #   restart: always
44
  #   ports:
45
  #     - "80:80"
46
  #     - "443:443"
47
  #   volumes:
48
  #     - ./dashboard/docs/Caddyfile.docker.example:/etc/caddy/Caddyfile:ro
49
  #     - caddy_data:/data
50
  #     - caddy_config:/config
51
  #   depends_on:
52
  #     - core
53
  #   networks:
54
  #     - maim_bot
55

56
  napcat:
57
    environment:
58
      - NAPCAT_UID=1000
59
      - NAPCAT_GID=1000
60
      - TZ=Asia/Shanghai
61
    ports:
62
      - "6099:6099"
63
    volumes:
64
      - ./docker-config/napcat:/app/napcat/config # 持久化napcat配置文件
65
      - ./data/qq:/app/.config/QQ # 持久化QQ本体
66
      - ./data/MaiMBot:/MaiMBot/data # 共享目录
67
    container_name: maim-bot-napcat
68
    restart: always
69
    image: mlikiowa/napcat-docker:latest
70
    networks:
71
      - maim_bot
72
  sqlite-web:
73
    # 注意：coleifer/sqlite-web 镜像不支持arm64
74
    image: coleifer/sqlite-web
75
    container_name: sqlite-web
76
    restart: always
77
    ports:
78
      - "8120:8080"
79
    volumes:
80
      - ./data/MaiMBot:/data/MaiMBot
81
    environment:
82
      - SQLITE_DATABASE=MaiMBot/MaiBot.db  # 你的数据库文件
83
    networks:
84
      - maim_bot
85

86
# volumes:         # 若需要持久化Python包时启用
87
#   site-packages:
88
#   caddy_data:
89
#   caddy_config:
90

91
networks:
92
  maim_bot:
93
    driver: bridge

几个值得注意的地方：

• EULA_AGREE 和 PRIVACY_AGREE：如果这两个环境变量没设置，第一次启动会卡在交互确认那里，Docker 环境下你没法在终端里回车，所以一定要带上。上面的值就是同意确认。
• MAIBOT_LEGACY_0X_UPGRADE_CONFIRMED=1：老版本迁移过来时跳过交互确认的，新装有没有都一样，不影响。
• WEBUI_HOST=0.0.0.0：必须设。不设的话 WebUI 只监听容器内部回环地址，宿主机通过端口映射也访问不到。
• 端口：WebUI 映射到宿主机的 18001，NapCat WebUI 是 6099，sqlite-web 是 8120。想改就改冒号左边，但记得记好，后面要访问。

创建目录并启动#

在你的部署目录下，先手动创建这些文件夹（compose 里的卷挂载到了一堆路径，目录不存在 Docker 会帮你建，但部分插件和日志目录最好先建好，避免权限问题）：

1
mkdir -p docker-config/mmc docker-config/napcat \
2
         data/MaiMBot-plugin-data data/MaiMBot/emoji \
3
         data/MaiMBot/plugins data/MaiMBot/logs \
4
         data/qq depends-data

对应关系如下（按上面 compose 里卷的挂载路径整理）：

然后启动：

1
docker compose up -d

第一次会从 Docker Hub 拉几个镜像，国内网络可能要等一会儿。

第一步：登录 QQ#

先在浏览器打开 http://你的服务器IP:6099，这是 NapCat 的 WebUI。进去会要一个 token：

这个 token 在容器日志里：

1
docker logs maim-bot-napcat

日志里会打印一行类似 Access Token: xxxxxxxx 的东西，复制进去就能进 WebUI 了。

进去之后先扫码登录自己的 QQ。这里提醒一句：MaiMBot 是拿你的 QQ 号当机器人用的，扫码登录之后这个号就是 bot 本体，建议用个小号，别把自己大号交给机器人。

登录成功之后，勾选上快速登录，后面重启容器就不用再扫码了：

第二步：开启正向 WebSocket#

在 NapCat WebUI 的网络配置里：

1. 新建或启用一个 正向 WebSocket / WebSocket 服务器。
2. 监听地址和端口默认即可，常用端口 3166。
3. 可以顺手设一个访问 Token。
4. IP 监听建议填 0.0.0.0，只监听回环地址的话后面的 MaiBot 容器连不进来。

这里有个关键点，端口要映射出去。因为 NapCat 和 MaiBot 是两个容器，MaiBot 要访问的是宿主机上映射出来的端口。compose 里 NapCat 只映射了 6099，如果你把 WebSocket 监听设在 3166，需要在 compose 的 napcat 服务里补上 "3166:3166" 再 docker compose up -d，启动后就能看到端口映射生效：

第三步：配置 MaiBot 适配器#

浏览器打开 http://你的服务器IP:18001，进 MaiBot 的 WebUI。首次进入需要 Access Token，同样去容器日志里找：

1
docker logs maim-bot-core

进去之后，在适配器里新建一个连接：

• 类型选 NapCat（OneBot） 相关适配器。
• 地址填 ws://宿主机IP或域名:3166（就是刚才 NapCat 监听的 WebSocket 地址）。
• 如果 NapCat 那边设了访问 token，这里填同一个。

第四步：加白名单#

这个项目默认是白名单模式，不把人和群加进去的话，机器人谁的消息都不回。在 WebUI 里把自己的 QQ 号和要用的群号加进白名单，保存。

不填白名单是最常见的”明明都部署好了就是不回消息”的原因，先查这里。

第五步：配置模型#

剩下的就是模型了，MaiMBot 支持各种 OpenAI 兼容接口。在 WebUI 的模型配置里填上你的 API 地址、Key 和模型名，保存之后到群里发条消息试试。key 攒多了不好管理的话，可以看看我写的 NewApi 部署教程，自建一个中转站统一收口。

踩坑记录#

1. WebUI 打不开：WEBUI_HOST 没设成 0.0.0.0，或者端口没映射对。
2. MaiBot 连不上 NapCat：WebSocket 监听地址不是 0.0.0.0，或者对应端口（如 3166）没映射。
3. 机器人不回复：先查白名单，绝大多数情况是白名单没加。
4. WebUI 登录密码忘了：可以在系统配置页面修改密码，或者查看容器日志里的初始 Access Token。
5. sqlite-web 报错：注意 coleifer/sqlite-web 镜像不支持 arm64，ARM 机器上别用这个镜像。

常用的管理操作#

• 修改 WebUI 登录密码：在系统配置页面的修改密码弹窗里操作，改完重启容器生效：

1
docker compose restart maim-bot-core

极简流程#

1. 写 compose 文件，创建各种数据目录。
2. docker compose up -d 启动三个容器。
3. 浏览器开 6099，日志里拿 token，扫码登录 QQ。
4. NapCat 里新建正向 WebSocket，监听 0.0.0.0:3166，端口映射出去。
5. 浏览器开 18001，日志里拿 token。
6. MaiBot 适配器里填 ws://宿主机IP:3166，连上。
7. 把 QQ 号和群号加白名单。
8. 填模型 API，收工。

效果#

我在127个视频上实测过，最终结果：

• 124个视频成功设为仅自己可见
• 3个之前就已经是仅自己可见，自动跳过
• 自动翻了13页，没有遗漏
• 不需要手动翻页，设好起止页数点开始就行

安装#

1
// ==UserScript==
2
// @name         B站批量隐藏投稿
3
// @namespace    https://bilibili.com/
4
// @version      9.0.0
5
// @description  批量将B站稿件设置为"仅自己可见"，支持自定义起止页，自动翻页
6
// @match        https://member.bilibili.com/platform/upload-manager/article*
7
// @match        https://member.bilibili.com/platform/upload/video/frame*
8
// @grant        none
9
// ==/UserScript==
10

11
(function () {
12
    'use strict';
13

14
    const ST = 'bili_batch_hide_v9';
15
    const QU = 'bili_batch_hide_queue_v9';
16
    const LIST_URL = 'https://member.bilibili.com/platform/upload-manager/article';
17
    const eUrl = b => 'https://member.bilibili.com/platform/upload/video/frame?type=edit&bvid=' + b;
18
    const slp = ms => new Promise(r => setTimeout(r, ms));
19

20
    function gs() { try { return JSON.parse(localStorage.getItem(ST)); } catch (e) { return null; } }
21
    function ss(s) { localStorage.setItem(ST, JSON.stringify(s)); }
22
    function cs() { localStorage.removeItem(ST); localStorage.removeItem(QU); }
23
    function gq() { try { return JSON.parse(localStorage.getItem(QU)) || []; } catch (e) { return []; } }
24
    function sq(q) { localStorage.setItem(QU, JSON.stringify(q)); }
25

26
    function curPg() {
27
        const m = location.href.match(/[?&]page=(\d+)/);
28
        return m ? parseInt(m[1]) : 1;
29
    }
30
    function isLP() { return location.href.includes('/upload-manager/article'); }
31
    function isEP() { return location.href.includes('/upload/video/frame'); }
32

33
    function collect() {
34
        const links = document.querySelectorAll('a[href*="/video/BV"]');
35
        const seen = new Set();
36
        const q = [];
37
        let sk = 0;
38
        links.forEach(a => {
39
            const m = a.href.match(/\/video\/(BV[a-zA-Z0-9]+)/);
40
            if (!m || seen.has(m[1])) return;
41
            seen.add(m[1]);
42
            const row = a.closest('li, div, [class*="item"]');
43
            if (row && row.textContent.includes('仅自己可见')) sk++;
44
            else q.push(m[1]);
45
        });
46
        return { queue: [...new Set(q)], skipped: sk };
47
    }
48

49
    function mkPanel() {
50
        if (document.getElementById('bs-panel')) return;
51
        const p = document.createElement('div');
52
        p.id = 'bs-panel';
53
        p.style.cssText = `
54
            position: fixed; z-index: 999999; right: 20px; top: 100px;
55
            width: 270px; padding: 15px; background: #18191c; color: #fff;
56
            border-radius: 10px; box-shadow: 0 4px 20px rgba(0,0,0,.35);
57
            font-size: 14px; font-family: Arial, sans-serif;
58
        `;
59
        p.innerHTML = `
60
            <div style="font-size:16px;font-weight:bold;margin-bottom:10px;">B站批量隐藏</div>
61
            <div id="bs-cur" style="margin-bottom:6px;color:#aaa;">当前页：第 ${curPg()} 页</div>
62
            <div id="bs-st" style="margin-bottom:10px;">状态：等待开始</div>
63
            <div id="bs-cnt" style="margin-bottom:12px;">已处理：0　跳过：0　失败：0</div>
64
            <div style="margin-bottom:8px;display:flex;align-items:center;gap:6px;flex-wrap:wrap;">
65
                <span style="font-size:12px;color:#aaa;">从第</span>
66
                <input id="bs-sp" type="number" min="1" max="99" value="1"
67
                    style="width:45px;padding:4px;border:1px solid #555;border-radius:4px;background:#2a2a2a;color:#fff;text-align:center;font-size:13px;">
68
                <span style="font-size:12px;color:#aaa;">页到第</span>
69
                <input id="bs-ep" type="number" min="1" max="99" value="99"
70
                    style="width:45px;padding:4px;border:1px solid #555;border-radius:4px;background:#2a2a2a;color:#fff;text-align:center;font-size:13px;">
71
                <span style="font-size:12px;color:#aaa;">页</span>
72
            </div>
73
            <button id="bs-go" style="width:100%;padding:8px;border:0;border-radius:6px;
74
                background:#00aeec;color:#fff;cursor:pointer;margin-bottom:6px;">开始批量隐藏</button>
75
            <button id="bs-stp" style="width:100%;padding:8px;border:0;border-radius:6px;
76
                background:#444;color:#fff;cursor:pointer;margin-bottom:6px;">停止</button>
77
            <button id="bs-rst" style="width:100%;padding:6px;border:0;border-radius:6px;
78
                background:#333;color:#aaa;cursor:pointer;font-size:12px;">重置状态</button>
79
            <div style="margin-top:10px;color:#aaa;font-size:12px;line-height:1.5;">
80
                自动翻页处理到结束页。<br>已"仅自己可见"的自动跳过。<br>面板在列表页和编辑页都会显示。
81
            </div>
82
        `;
83
        document.body.appendChild(p);
84

85
        const sp = localStorage.getItem('bs_sp');
86
        const ep = localStorage.getItem('bs_ep');
87
        if (sp) document.getElementById('bs-sp').value = sp;
88
        if (ep) document.getElementById('bs-ep').value = ep;
89

90
        document.getElementById('bs-sp').onchange = () => localStorage.setItem('bs_sp', document.getElementById('bs-sp').value);
91
        document.getElementById('bs-ep').onchange = () => localStorage.setItem('bs_ep', document.getElementById('bs-ep').value);
92

93
        document.getElementById('bs-go').onclick = function () {
94
            if (gs() && gs().running) { stUI('运行中，请先停止'); return; }
95
            const sp = Math.max(1, parseInt(document.getElementById('bs-sp').value) || 1);
96
            const ep = Math.max(sp, parseInt(document.getElementById('bs-ep').value) || 99);
97
            cs();
98
            ss({
99
                running: true, collected: false, reachedStart: false,
100
                processed: 0, skipped: 0, failed: 0, queue: [],
101
                startPage: sp, endPage: ep, currentPage: 0, done: false
102
            });
103
            sq([]);
104
            localStorage.setItem('bs_sp', String(sp));
105
            localStorage.setItem('bs_ep', String(ep));
106
            stUI('开始（第 ' + sp + '~' + ep + ' 页）');
107
            location.href = LIST_URL + (sp > 1 ? '?page=' + sp : '');
108
        };
109

110
        document.getElementById('bs-stp').onclick = () => { cs(); stUI('已停止'); updP(); };
111
        document.getElementById('bs-rst').onclick = () => { cs(); stUI('已重置'); updP(); };
112
    }
113

114
    function updP() {
115
        const s = gs();
116
        const el = document.getElementById('bs-cnt');
117
        const pel = document.getElementById('bs-cur');
118
        if (el && s) el.textContent = '已处理：' + (s.processed || 0) + '　跳过：' + (s.skipped || 0) + '　失败：' + (s.failed || 0);
119
        else if (el) el.textContent = '已处理：0　跳过：0　失败：0';
120
        if (pel) pel.textContent = '当前页：第 ' + curPg() + ' 页（目标 ' + (s ? s.startPage + '~' + s.endPage : '-') + '）';
121
    }
122
    function stUI(t) { const el = document.getElementById('bs-st'); if (el) el.textContent = '状态：' + t; }
123

124
    function advance() {
125
        const s = gs();
126
        if (!s || !s.running || !isLP()) return;
127
        if (s.done) return;
128

129
        s.currentPage = curPg();
130
        ss(s);
131
        updP();
132

133
        if (!s.reachedStart) {
134
            if (curPg() < s.startPage) {
135
                stUI('跳转到第 ' + s.startPage + ' 页...');
136
                location.href = LIST_URL + '?page=' + s.startPage;
137
                return;
138
            }
139
            s.reachedStart = true;
140
            ss(s);
141
        }
142

143
        if (curPg() > s.endPage) { finish(); return; }
144

145
        if (!s.collected) {
146
            const { queue, skipped } = collect();
147
            if (queue.length === 0 && document.querySelectorAll('a[href*="/video/BV"]').length === 0) {
148
                stUI('等待页面加载...');
149
                setTimeout(() => { if (gs() && gs().running && !gs().done) advance(); }, 2000);
150
                return;
151
            }
152
            s.skipped = (s.skipped || 0) + skipped;
153
            s.queue = queue;
154
            s.collected = true;
155
            ss(s);
156
            sq(queue);
157

158
            if (queue.length === 0) {
159
                stUI('本页无待处理，进入下一页');
160
                s.collected = false; ss(s); nextPage();
161
                return;
162
            }
163
            goEdit();
164
            return;
165
        }
166

167
        if (s.queue.length > 0) { goEdit(); return; }
168
        s.collected = false; ss(s); nextPage();
169
    }
170

171
    function goEdit() {
172
        const s = gs();
173
        if (!s || !s.running) return;
174
        if (!s.queue || s.queue.length === 0) { advance(); return; }
175
        const next = s.queue.shift();
176
        sq(s.queue);
177
        ss(s);
178
        stUI('处理 ' + next + ' | 第 ' + s.currentPage + '/' + s.endPage + ' 页');
179
        location.href = eUrl(next);
180
    }
181

182
    function nextPage() {
183
        const s = gs();
184
        if (!s || !s.running || s.done) return;
185
        if (curPg() >= s.endPage) { finish(); return; }
186
        stUI('进入第 ' + (curPg() + 1) + ' 页...');
187
        s.collected = false; ss(s);
188
        location.href = LIST_URL + '?page=' + (curPg() + 1);
189
    }
190

191
    function finish() {
192
        const s = gs(); if (!s) return;
193
        s.done = true; ss(s);
194
        const msg = '🎉 全部完成！\n处理：' + (s.processed || 0) + '，跳过：' + (s.skipped || 0) + '，失败：' + (s.failed || 0);
195
        alert(msg); cs(); stUI('全部完成');
196
    }
197

198
    async function handleEP() {
199
        const s = gs();
200
        if (!s || !s.running || s.done) return;
201
        updP(); stUI('正在编辑...');
202
        await slp(2000);
203

204
        let ok = false, clicked = false;
205
        const labels = document.querySelectorAll('span.label');
206
        for (const l of labels) { if (l.textContent.trim().startsWith('更多设置')) { l.click(); clicked = true; break; } }
207
        if (!clicked) {
208
            const titles = document.querySelectorAll('div.title');
209
            for (const t of titles) { if (t.textContent.trim().startsWith('更多设置')) { t.click(); clicked = true; break; } }
210
        }
211
        if (!clicked) {
212
            const all = document.querySelectorAll('span, div, a');
213
            for (const e of all) { if (e.textContent.trim().startsWith('更多设置')) { e.click(); clicked = true; break; } }
214
        }
215

216
        if (clicked) {
217
            await slp(1200);
218
            const containers = document.querySelectorAll('.check-radio-v2-container');
219
            if (containers.length >= 2) {
220
                const isChecked = containers[1].querySelector('.check-radio-v2-box-checked') !== null;
221
                if (!isChecked) {
222
                    const radio = containers[1].querySelector('.check-radio-v2-box, span');
223
                    if (radio) radio.click(); else containers[1].click();
224
                    await slp(800);
225
                }
226
                const sub = document.querySelector('span.submit-add');
227
                if (sub) { sub.click(); ok = true; }
228
                else {
229
                    const all = document.querySelectorAll('div, button, span');
230
                    for (const e of all) { if (e.textContent.trim() === '立即投稿') { e.click(); ok = true; break; } }
231
                }
232
            }
233
        }
234

235
        const st = gs();
236
        if (st) { if (ok) st.processed = (st.processed || 0) + 1; else st.failed = (st.failed || 0) + 1; ss(st); }
237
        updP();
238
        stUI(ok ? '已提交，返回列表...' : '失败，返回列表...');
239
        await slp(2500);
240
        const st2 = gs();
241
        const pg = st2 && st2.currentPage ? st2.currentPage : 1;
242
        location.href = LIST_URL + (pg > 1 ? '?page=' + pg : '');
243
    }
244

245
    setTimeout(function () { mkPanel(); updP(); }, 500);
246

247
    if (isLP()) {
248
        setTimeout(function () {
249
            const s = gs();
250
            if (s && s.running && !s.done) { stUI('自动继续...'); updP(); advance(); updP(); }
251
        }, 2000);
252
    }
253

254
    if (isEP()) { handleEP(); }
255
})();