{ "version": "https://jsonfeed.org/version/1", "title": "Biulight 文档 Blog", "home_page_url": "https://blog.biulight.top/timeline/blog", "description": "Biulight 文档 Blog", "items": [ { "id": "https://blog.biulight.top/timeline/blog/shine-ubuntu-server", "content_html": "

拿到一台新的 Ubuntu 服务器后，可以用 Shine 统一完成常用命令行工具的安装和 shell profile 配置。相比逐条复制安装脚本，Shine 可以先预览将要执行的步骤，并记录已经初始化的项目，方便之后检查状态。

\n

本文使用适合生产服务器的 minimal profile，安装 Neovim、fzf、bat、eza 和 zoxide，不包含 shell 历史同步、提示符、Node.js 工具链或 Homebrew。

\n

开始前​

\n

请先确认：

\n\n

系统初始化可能安装软件包、下载程序并更新 shell profile。正式执行前先使用 --dry-run 检查实际步骤。

\n

安装 Shine​

\n

运行官方安装脚本：

\n
curl -fsSL https://github.com/biulight/shine/releases/latest/download/install.sh | sh
\n

默认安装位置是 ~/.local/bin/shine，安装脚本不会修改 shell 配置。确认 ~/.local/bin 已加入 PATH，再检查版本：

\n
export PATH=\"$HOME/.local/bin:$PATH\"
shine --version
\n

需要设置永久 PATH、指定安装目录或固定版本时，请查看 Shine 的安装与升级说明。

\n

预览服务器配置​

\n

先查看当前版本为 Ubuntu 提供的初始化项目：

\n
shine sys list
shine sys bootstrap --preset minimal --dry-run
\n

第二条命令只打印选择结果、脚本调用和 profile 更新，不修改系统。确认项目和目标路径符合预期后，再继续执行。

\n

应用 minimal profile​

\n
shine sys bootstrap --preset minimal
\n

过程中可能因为安装系统软件而请求 sudo 权限。完成后查看 Shine 记录的初始化状态：

\n
shine sys status
\n

如果以后想检查这些软件是否有可用更新，可以运行：

\n
shine sys update
\n

该命令只检查由 shine sys bootstrap 记录的软件，不会自动安装升级。

\n

需要更完整的终端环境​

\n

minimal 适合保持精简的生产服务器。如果这是开发机，或你还需要 AstroNvim、Atuin、Yazi、Starship 和 zsh-vi-mode，可以先预览 recommended profile：

\n
shine sys bootstrap --preset recommended --dry-run
\n

确认后去掉 --dry-run 即可应用。Ubuntu 还提供包含 ZeroTier、pnpm、mise 和 Homebrew 的 all profile；建议先对照内置预设清单，不要在服务器上安装不需要的组件。

\n

更多交互选择、下载代理和受管系统配置的用法，见 Shine 中文手册的初始化与管理系统。

", "url": "https://blog.biulight.top/timeline/blog/shine-ubuntu-server", "title": "使用 Shine 快速配置 Ubuntu 服务器", "summary": "拿到一台新的 Ubuntu 服务器后，可以用 Shine 统一完成常用命令行工具的安装和 shell profile 配置。相比逐条复制安装脚本，Shine 可以先预览将要执行的步骤，并记录已经初始化的项目，方便之后检查状态。", "date_modified": "2026-08-19T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Shine", "Linux", "Ubuntu" ] }, { "id": "https://blog.biulight.top/timeline/blog/ai-in-production-migration", "content_html": "

AI 可以很快读完一个仓库、列出迁移清单、批量修改代码；但在一个缺少业务和技术文档、仍在生产运行的\n系统里，“改得快”并不等于“可以上线”。这次 Vue 2 → Vue 3 迁移让我更确信：AI 最合适的位置不是\n替代工程判断，而是进入一套有阶段、有证据、有回归边界的交付流程。

\n

这篇文章不讨论 Vue API 本身，而是记录 AI 如何参与一个陌生生产系统的迁移：先收集事实、生成可审查\n计划，再分批实施、手工验收，并把每次发现沉淀成下一轮可复用的规则。有关 Vue 迁移的技术细节见\nkeystone-web 从 Vue 2 到 Vue 3：一场两段式迁移的复盘。

\n

起点：代码很多，文档很少，不能假装自己已经理解业务​

\n

项目是一个中大型管理后台，有数百个 Vue 组件、权限路由、复杂表格、多个媒体类型的业务流程，以及\n持续使用中的生产环境。接手时我并不熟悉业务，相关技术与业务文档也不完整。

\n

在这种条件下，最危险的 AI 使用方式是把问题简化成一句“升级到 Vue 3”，然后接受一份看似完整的\n改动。模型可以根据常见迁移模式给出合理建议，却不知道某个 params 是否承载业务身份、某个表格的\n事件是否被下游依赖，或者一个管理员账号是否绕过了普通用户必经的权限路径。

\n

因此先确定了一个原则：AI 不能以推断取代项目事实；每个结论都要有代码、测试、构建结果或手工观察\n作为落点。

\n

先降低未知数：不要同时替换所有基础设施​

\n

迁移被拆成两段。第一段先将 Vue CLI 迁到 Rsbuild，但仍保持 Vue 2.7 上线。随后用约半年的稳定运行期\n理解系统、清理无用代码与技术债，并在新改动中优先采用 Vue 2.7 和 Vue 3 共用的能力，例如\nComposition API 和新插槽语法。

\n

这一步不是“拖慢升级”，而是在为 AI 和人都创造更好的问题边界。等正式开始 Vue 3 迁移时，构建器、\n环境变量、开发与生产构建已经经过验证；排查一个问题时，不必再同时怀疑 Rsbuild、Vue 运行时和业务\n逻辑。先减少变量，之后的自动化才有可信的上下文。

\n

用 AI 写计划前，先给它经过核实的输入​

\n

计划阶段使用 Fable 5，但它不是从一句模糊需求开始猜。输入先由全仓检索和依赖排查组成，包括：

\n\n

Fable 5 在这些事实之上生成迁移策略和 PRD：比较全量重写、长期 compat、微前端隔离三种路线；定义\n基线、基础设施、第三方库、机械替换、公共组件、业务模块、测试升级和收尾验收等阶段；再为每一批\n列出依赖关系和验证方式。

\n

这里真正有价值的不是“AI 写出了一份很长的计划”，而是计划可以被审查、被纠正、被执行。比如\nslot=\"...\" 的 122 个命中并不等于 122 个模板迁移点：其中混有 JSX 中合法的属性和注释。把这个\n前提写进 PRD，就能阻止后续执行模型做危险的全局替换。

\n

实施时，把模型当作分批交付者，而不是一次性重写器​

\n

Opus 4.7 与 Sonnet 5 按 PRD 分批实施。每个批次都有清楚的范围和退出条件：例如先让基础设施能进入\n登录页，再替换 Element UI 和 VXE Table，并用真实列表页验证；之后才处理 .sync、插槽、指令等\n全仓变化；最后按公共组件、业务模块的依赖顺序推进。

\n

这套节奏给 AI 加了三层约束：

\n
    \n
  1. 改动范围小。 每一批聚焦一类依赖或一个模块，失败时能回到明确的 diff。
    2. \n
  2. 验证紧随改动。 构建、lint、单测、E2E 和手工页面验证按阶段执行，不等到最后才发现问题。
    3. \n
  3. 不夹带“顺手优化”。 迁移期间发现的无关重构只记录，不在同一批改动中扩张范围。
    4. \n
\n

模型很擅长重复性工作：全仓盘点、模式转换、补齐大量相似调用点、汇总失败清单。它不擅长在缺少上下文\n时猜测某个行为是否是业务约定。因此，批次拆分的意义不是限制 AI 的速度，而是让每次推断都有机会被\n最小范围的验证推翻。

\n

真实反例：一个看似合理的路由规则如何造成回归​

\n

最有教育意义的不是成功案例，而是一次错误的启发式。

\n

迁移 Vue Router 3 到 4 时，曾把“内部 router.push() 应使用 query，构造可分享链接的\nrouter.resolve() 应使用 params”当作批量修改规则。这个规则很顺口，但它是错的。

\n

真正决定参数位置的是目标路由的 path：未声明动态段的值使用 query；必填动态段必须使用\nparams；可选动态段再按约定选择。错误规则把某个内部跳转的必填 id 放进 query，结果在点击列表\n行时同步抛出 Missing required param，跳转被直接阻断。

\n

这次错误没有被隐藏。它被修复后，完整的根因、适用规则和反例被写进迁移记录，并进一步沉淀为项目\n记忆。下一轮 Claude Code 会话不需要“记得上一次聊天”，只需要读取这条规则。

\n

我认为这正是 AI 编程在生产环境里最重要的能力之一：把失败从一次对话中的偶然经验，变成仓库中可\n检查、可复用、可更新的知识。

\n

测试覆盖不是安全感：手工验收负责发现模型和用例的共同盲区​

\n

自动化用例能保证核心路径持续可跑，却不天然保证覆盖正确。一次手工回归发现，已有 Playwright 冒烟\n只用管理员账号登录；管理员恰好绕开了普通角色才会走到的 Campaign 详情重定向，因此上述路由回归\n没有被 E2E 捕获。

\n

手工验收还发现过很多“构建、lint、单测都正常”的问题：动态组件在页面显示 [object Promise]、\nElement Plus 日期控件因格式 token 或裸 default-time 解析失败而显示错误日期、全局 passive 事件\n补丁让下拉组件的鼠标选择失效。这些问题往往需要真实数据、空状态、特定角色或连续交互才能出现。

\n

所以手工验收不是自动化测试的低配替代，而是专门覆盖高不确定性区域的另一层测试。对管理后台而言，\n至少应显式覆盖：

\n\n

每个手工发现都应有去向：补成自动化用例、加入手工清单，或提炼为迁移规则。没有去向的“已修复”只是\n下一次回归的候选。

\n

AI 需要的不只是上下文窗口，而是项目记忆系统​

\n

这次实践中，迁移信息被拆成不同层次保存：

\n
载体负责回答的问题
迁移 PRD为什么采用这条路线、阶段如何依赖、每批如何验收
迁移问题记录具体故障的现象、根因、修复方式与回归规则
项目 AGENTS.md当前技术栈、开发约束、验证命令和禁止重新引入的兼容层
项目记忆一条会在后续任务反复使用的精确规则，例如路由参数边界
Git 提交与测试改动的可审查证据、可回退边界与行为验证
\n

这种分层比把所有信息塞进一个超长提示词更可靠。提示词会过期、上下文会被截断、不同模型的理解也会\n不同；而仓库里的文档、规则和测试可以随实现变化一起维护。

\n

我会继续坚持的边界​

\n

AI 参与生产改造时，我会把下面几条当作默认约束：

\n
    \n
  1. 让 AI 先完成全仓盘点和证据收集，再由人工审查盘点结论、范围与风险后制定方案。
    2. \n
  2. 将大迁移拆成可独立验证、可回退的小批次。
    3. \n
  3. 对 API 行为、权限、路由和组件库差异，优先相信源码、测试和真实页面，而不是“通常如此”。
    4. \n
  4. 把模型造成或发现的错误写成规则和测试，而不是只留在聊天记录里。
    5. \n
  5. 保留人工验收，特别是角色、空状态、视觉和连续交互路径。
    6. \n
  6. 不把迁移、性能优化和业务重构混在同一轮交付中。
    7. \n
\n

AI 没有让生产迁移变成零风险工作；它减少的是盘点、重复修改和信息整理的成本。真正让风险可控的，\n仍然是清晰的范围、持续的验证、可回退的提交，以及愿意把错误沉淀下来的人。

", "url": "https://blog.biulight.top/timeline/blog/ai-in-production-migration", "title": "AI 参与生产系统迁移：把模型能力放进可验证的交付流程", "summary": "AI 可以很快读完一个仓库、列出迁移清单、批量修改代码；但在一个缺少业务和技术文档、仍在生产运行的", "date_modified": "2026-08-07T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "AI", "Claude Code", "Fable", "Opus", "Sonnet", "Software Engineering", "Migration" ] }, { "id": "https://blog.biulight.top/timeline/blog/vue2-to-vue3-migration", "content_html": "

把一个有 331 个 .vue 组件、仍在持续迭代的管理后台从 Vue 2 迁到 Vue 3，最危险的想法是：\n“把依赖升级完，再把报错逐个修掉。”真正的迁移对象并不只有 Vue，而是路由、状态管理、UI 库、\n表格封装、构建链、测试和数百个已经被用户使用的交互。

\n

这次升级实际上分成了两段：先将 Vue 2.x + Vue CLI 迁到 Vue 2.7 + Rsbuild 并上线；随后让它在线上\n稳定运行约半年，在这段时间持续清理技术债、删除不再需要的代码、尽量精简实现；最后才将已经稳定的\nVue 2.7 应用升级到 Vue 3。第二段在专用分支中阶段化完成，旧版本继续承接发布，迁移版本验收后再\n整体切换。它没有演变成业务重写，也没有趁机换 Pinia 或 Vite；这份克制比任何 API 转换技巧都更重要。

\n
阶段主要工作结束条件
第一段：构建迁移Vue CLI → Vue 2.7 + Rsbuild，保持业务行为新构建链上线并稳定运行
稳定与清债期熟悉业务边界，删除无用代码，使用跨 Vue 2.7 / Vue 3 的 API业务边界逐步明确，待迁移代码范围收敛
第二段：运行时迁移Vue 3、Router 4、Element Plus、VXE Table 4 与测试体系升级移除兼容层，完成自动化与手工验收
\n

第一段：先把构建系统换掉，再给业务留出稳定期​

\n

第一段从 Vue CLI 5 迁到 Rsbuild 时，应用仍运行在 Vue 2.7。目标不是借机升级框架，而是将构建链\n现代化并消除已经没有价值的历史配置：移除 Vue CLI 及其插件、删除 vue.config.js 等旧配置，改用\nrsbuild.config.mjs；SVG 从不兼容 Rspack 的 svg-sprite-loader 改为原生 asset/source 加载，\n组件的使用方式保持不变。

\n

采用这条路线也有现实原因：接手时我对这个项目并不熟悉，手上缺少完整的业务与技术文档。此时若同时\n替换构建器、运行时、组件库并修改业务逻辑，任何异常都很难回答“它来自旧行为、构建链、Vue 3，还是\n我尚未理解的业务规则”。先把范围收缩为 Vue 2.7 + Rsbuild 上线，才能在不改变主要业务语义的前提下\n建立对系统的认识。

\n

这次迁移也统一了浏览器端环境变量边界。业务代码从 process.env.VUE_APP_* 改为\nimport.meta.env.VUE_APP_*；少数第三方包所需的 process.env 则只在构建配置中提供兼容 shim。\n这样既避免浏览器里的 process is not defined，也不需要为了兼容旧写法继续在业务代码中传播\nNode.js 运行时假设。

\n

Rsbuild 上线后，项目在 Vue 2.7 状态继续正常迭代约半年。这段稳定期的重点不是继续验证已经上线的\n构建工具，而是让团队通过日常需求和真实业务流程，逐步确认业务边界与历史行为。在这个过程中，团队\n持续清理技术债、删除非必要代码，让后续需要维护和迁移的范围更小、更清晰。等到 Vue 3 迁移启动时，\n面对的是一套业务基线清楚、代码范围已经收敛的系统，不再需要一边迁移一边猜测旧逻辑。

\n

这也是两段式路线最大的收益——先完成构建工具切换，再留出理解业务和收敛代码的稳定阶段，避免把\n构建系统变化、Vue 运行时升级和组件库替换压在同一批改动中。第二阶段因此可以把注意力集中在 Vue 3\n迁移本身。

\n

Vue 2.7 不是终点，而是 Vue 3 的预备跑道​

\n

这半年的重构并非只做删除。Vue 2.7 原生提供了 Composition API，因此在新增或调整逻辑时，优先选用\nref、reactive、computed、watch、onMounted 等 Vue 2.7 与 Vue 3 都支持的能力；保留既有\nOptions API，但不再继续扩散只服务于 Vue 2 的写法。这样做不会改变已经稳定的页面风格，却能让每一次\n局部维护都向 Vue 3 靠近。

\n

this.$set 是典型例子。Vue 2 需要它来让新增对象属性或数组索引更新具备响应式；Vue 3 基于 Proxy，\n普通赋值已经会响应。预备期内，改到相关代码时就倾向写成 object[key] = value 或\narray[index] = value，而不是继续引入 $set。这既减少了后续迁移的工作量，也让代码表达的意图更\n直接。

\n

ESLint 在这个过程中承担的是“逐步收紧的迁移护栏”，而不是一次性把历史代码全部打红。Vue 2.7 阶段，\n为避免存量项目立刻被遗留写法阻断，曾对 v-bind.sync、$set / $delete 相关的废弃规则保留豁免；\n同时约束新增或重构代码不要继续引入这些 Vue 2 专属模式。正式切到 Vue 3 后，配置目标才改为 Vue 3.5\n并移除豁免，让 lint 明确报出 .sync、旧销毁生命周期、.native、$listeners 等不再可用的写法，\n而不是让它们在运行时才暴露。

\n

这条护栏最终找出了 18 个文件中的 48 处 $set 调用，并将它们全部替换为普通对象或数组赋值；项目里\n没有实际的 $delete 调用。14 个文件中的 20 处 .native 以及 destroyed / beforeDestroy 生命周期，\n则属于切换到 Vue 3 运行时之后才能处理的破坏性变更：它们分别改为 Vue 3 的事件透传方式和\nunmounted / beforeUnmount。后者不能提前放进 Vue 2.7 代码库。重要的不是这些数字本身，而是节奏：\n先让新的维护代码不再制造 Vue 2 专属债务，再在运行时切换后用规则集中清理只能由 Vue 3 支持的写法。

\n

插槽也遵循同一原则。Vue 2.7 已支持 Vue 3 使用的 v-slot / # 语法，因此在持续重构中，模板插槽\n应从旧的 slot=\"name\"、slot-scope=\"scope\" 迁向 #name=\"scope\"。例如：

\n
<!-- Vue 2 旧写法：Vue 3 不支持 -->
<template slot=\"default\" slot-scope=\"scope\">
  {{ scope.row.name }}
</template>

<!-- Vue 2.7 与 Vue 3 都支持 -->
<template #default=\"scope\">
  {{ scope.row.name }}
</template>
\n

不过这不是一次安全的全文替换。全仓检索到 122 个 slot=\"...\" 命中，其中混有真正需要迁移的模板、\nJSX render 中合法的 slot 属性，以及注释里的死代码。正确做法是先让新增和改动的模板采用\nv-slot，再在 Vue 3 阶段逐个分类处理存量命中；把 JSX 一并替换反而会制造新的问题。

\n

AI 的角色：先生成可审查的计划，再分批执行​

\n

全仓盘点完成后，Fable 5 基于已核实的依赖、特殊用法和范围边界生成迁移 PRD；Opus 4.7 与 Sonnet 5\n再按阶段、任务批次和验证门槛实施。Claude Code 则把手工验收中发现的现象、根因和规则持续沉淀到\n迁移记录与项目记忆中。AI 加速了盘点、模式化修改与信息整理，但每一个结论仍须由代码、测试、构建\n结果或手工观察验证。

\n

这套协作方式、一次路由参数误判造成的回归，以及自动化和人工验收如何互补，详见\nAI 参与生产系统迁移：把模型能力放进可验证的交付流程。

\n

先做选择：为什么不是长期渐进迁移​

\n

进入第二段时，项目已经是 Vue 2.7、Vue Router 3、Vuex 3、Element UI 2、VXE Table 3、\nvue-i18n 8 和 Rsbuild 的组合。目标是 Vue 3.5、Vue Router 4、Vuex 4、Element Plus、VXE Table 4\n和 vue-i18n 9，同时保留已经稳定的 Rsbuild 与既有 Vuex 模块结构。

\n

一开始看起来有三条路：全量重写、长期使用 @vue/compat 渐进迁移，或用微前端让两套运行时并行。\n最后都不适合这个项目：

\n\n

于是选择“阶段化的一次性迁移”。@vue/compat 只在中间阶段以 MODE 2 运行，用运行时警告当作\n迁移待办扫描器；发布前必须移除。这个边界很关键：兼容层可以帮助发现问题，但不能成为问题被搁置的\n理由。

\n

先固定什么都不改时的基线​

\n

迁移第一步不是改 main.js，而是建立可回归的事实基线。

\n

项目先补齐并跑通 Playwright 冒烟链路：登录、Dashboard、Campaign 列表和分页、报表、组织管理\n弹窗。它们覆盖了权限路由、VXE Table、Element UI 表单和常见异步请求。与此同时，用\npnpm analyze 记录生产包体：迁移前未压缩总大小为 15345.0 kB，gzip 后为 7397.6 kB。

\n

这份基线让后续每一个“看起来像 Vue 3 问题”的现象都有判断依据：它是原有问题、迁移回归，还是\n尚未覆盖的新路径。没有它，构建通过只会给人错误的安全感。

\n

分阶段切换：先打通运行时，再迁业务​

\n

迁移没有按目录从上到下改，而是按依赖关系推进。

\n

第一阶段替换框架基础设施：Rsbuild 的 Vue 2 插件换成 Vue 3 插件，new Vue() 改为\ncreateApp()，Vue.prototype 改到 app.config.globalProperties，路由切到\ncreateRouter() / createWebHistory()，并将动态路由注册从 addRoutes 改为逐条 addRoute。\nVuex 3 升 Vuex 4 后，已有五个 namespaced 模块的业务 API 基本不需要改；vue-i18n 9 则采用\nlegacy 模式，降低了模板国际化调用的改造量。

\n

第二阶段才整体替换第三方库：Element UI → Element Plus，VXE Table 3 → 4，并接入与 Element\nPlus 对应的 VXE 渲染插件。紧接着处理 Vue 3 的机械性变化，例如 .sync 改 v-model:prop、\n指令钩子改名、过时插槽语法、$listeners、$scopedSlots 和 test-utils v2 的配置变化。

\n

机械替换也有边界。全仓有 151 处 .sync，可以分批转换并结合 diff 与构建检查；但 slot=\"...\"\n命中了 122 个文件，其中既有待迁的模板语法，也有合法的 JSX 属性和注释。对它全局替换会直接破坏\n代码。类似地，路由守卫、全局指令、BiuTable / selectgrid 这类 VXE Table 深度封装，以及\nBiuDialog / BiuForm 这样的基础组件，都必须按实际行为人工审查。

\n

业务页面放到最后，并按依赖与规模推进：先公共页、登录、Dashboard，再到系统配置、报表、订单，\n最后才是近百个组件的 Campaign 模块。每批变更独立提交，并在进入下一批前运行构建、单测和对应\n页面的手工验证。这样出现回归时，排查范围仍然可控。

\n

每个阶段采用的验证目标也不同：基础设施阶段先验证应用能到登录页；替换组件库后验证 Dashboard\n和一个 VXE Table 列表；公共组件阶段为每一批组件找一个宿主页面；业务模块阶段再执行相应 E2E 与\n完整手工清单。最后才同时要求 lint、单测、生产构建、E2E、兼容警告清理和包体对比。把验证放在\n阶段门槛上，比在最后堆一次全量测试更容易定位问题。

\n

验收阶段发现：最棘手的错误往往不在构建期​

\n

下面几个问题都没有被“构建成功”捕获，却最能说明为什么迁移需要真实页面和真实交互的回归。

\n

动态组件渲染出 [object Promise]​

\n

Vue 2 会把 :is 接收的 () => import('./Component.vue') 当作异步组件工厂；Vue 3 不再隐式做\n这个判断。Campaign 详情页按媒体类型切换子组件时，页面没有报错，只是渲染出了\n[object Promise]。

\n

修复是显式使用 defineAsyncComponent(() => import('./Component.vue'))。这是一个很好的提醒：\n静态检查能发现类型和语法问题，但无法替代“实际点开动态分支”的验证。

\n

Vue Router 4 中 params 与 query 不能凭习惯替换​

\n

迁移时若向没有动态路径段的路由传 params，Vue Router 4 会丢弃它并给出警告；而把本应填入必填\n动态段的值改放到 query，又会直接抛出 Missing required param，使跳转失败。

\n

最终采用的规则不是“push 用 query、resolve 用 params”，而是只看目标路由的 path：

\n\n

这条规则后来也指导了可分享 Campaign 链接和内部跳转的收敛，避免了“页面能打开但详情参数丢失”的\n静默回归。

\n

这里还有一个值得记录的过程教训：最初的错误启发式是“内部 push() 用 query，构造可分享链接的\nresolve() 用 params”。它听起来合理，却忽略了路由定义本身；一次批量替换后，普通列表点击也因\n缺少必填 id 而被阻断。修复后，这条规则被单独写入项目记忆。对于 AI 参与的大范围迁移，记录\n“曾经为什么改错”与记录最终写法同样重要。

\n

Element Plus 的日期问题会静默污染业务值​

\n

Element UI 的日期格式使用 yyyy、dd 等小写 token；Element Plus 基于 dayjs，正确写法是\nYYYY、DD。错误 token 不只让输入框显示 Su/02/yyyy 这类乱码，打开面板后会发现实际选中日期\n已经错位。

\n

另一个更隐蔽的问题是 default-time=\"['00:00:00', '23:59:59']\"。在 Element Plus 中，裸时间\n字符串会被解析为 Invalid Date；当日期范围控件没有绑定值时，内部日期计算继而变成 NaN，日历\n面板整体失效。解决方式是使用完整且合法的日期时间字符串，例如\n'2000-01-01 00:00:00'。这类差异无法靠 API 名称替换发现，必须在“编辑已有数据”和“新建空数据”\n两种场景中分别打开控件核验。

\n

全局性能补丁会破坏组件交互​

\n

Campaign 表单中的 vue-multiselect 出现了鼠标点选即关闭、值无法回填的问题，程序化\nelement.click() 却正常。根因不是组件库或弹窗焦点，而是旧项目引入的\ndefault-passive-events：它把 mousedown 也强制设为 passive，导致组件内部用于保持焦点的\npreventDefault() 失效。

\n

修复不是给每个下拉框补事件，而是替换全局补丁，只将 scroll、wheel、touch* 等真正可能阻塞\n滚动的事件设为 passive，保留鼠标按键事件的默认行为。迁移过程中遇到“许多地方同时出问题”时，\n先检查全局拦截器、样式覆盖和事件补丁，往往比逐页修补更有效。

\n

自动化回归不等于验收：角色和空状态必须进入清单​

\n

迁移中的 Playwright 冒烟用例覆盖了登录、Dashboard 和核心列表，但一次后续排查发现，它只使用\n管理员账号。管理员的权限路由恰好绕过了非管理员才会经过的 Campaign 详情重定向，因此路由参数的\n问题没有在 E2E 中出现，而是在手工以普通角色进入详情时才暴露。

\n

这不是“自动化测试没价值”，而是覆盖模型不完整。对于权限驱动的管理后台，回归清单至少还应包含：

\n\n

手工 QA 的价值不是重复点一遍自动化脚本，而是专门覆盖权限、真实数据形态和视觉交互这些很难在\n一次通用冒烟中穷尽的变量。每个发现都应回流为新的自动化用例、手工检查项，或至少是一条有边界的\n迁移规则。

\n

构建产物：不能只看是否超过预算​

\n

最终移除 @vue/compat 后，生产包体为 17566.2 kB（未压缩）和 8569.6 kB（gzip），相对基线增长\n14.5% 和 15.8%，超过了最初设定的 ±10% 目标。

\n

分析结果表明，这不是一次偶然的打包回归：本次刻意保持 Element Plus 全量引入以控制迁移范围，而\nVXE Table 4 的运行时也更重。若要把体积拉回预算，需要单独规划 Element Plus 按需引入和相关验证，\n而不是在迁移收尾时混入一次性能优化。把“功能迁移正确”与“下一阶段的优化机会”分开记录，能让交付\n结论保持诚实，也不会掩盖后续工作。

\n

这次迁移留下的做法​

\n
    \n
  1. 先定义不变项：本次不改业务逻辑、不换状态管理、不换构建器，避免范围膨胀。
    2. \n
  2. 让兼容层只做临时诊断工具，并把移除它作为验收条件。
    3. \n
  3. 将可机械化的修改和需要人工判断的修改分开管理，拒绝“一把梭”的全局替换。
    4. \n
  4. 用登录、列表、表单、详情和弹窗建立真实冒烟基线；构建通过不是功能通过。
    5. \n
  5. 每一类迁移差异都记录成“现象、根因、修复规则、回归场景”，让后续维护不必重新踩坑。
    6. \n
\n

Vue 2 到 Vue 3 的迁移不是为了把所有组件写成 <script setup>。对一个正在运行的业务系统来说，\n更有价值的结果是：应用在原生 Vue 3 运行时上稳定交付，关键交互得到验证，且每一条兼容性债务都有\n明确的边界和去向。

", "url": "https://blog.biulight.top/timeline/blog/vue2-to-vue3-migration", "title": "keystone-web 从 Vue 2 到 Vue 3：一场两段式迁移的复盘", "summary": "把一个有 331 个 .vue 组件、仍在持续迭代的管理后台从 Vue 2 迁到 Vue 3，最危险的想法是：", "date_modified": "2026-08-07T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Vue", "Vue 2", "Vue 3", "Element Plus", "Rsbuild", "Migration" ] }, { "id": "https://blog.biulight.top/timeline/blog/nginx-ui-https-certificate", "content_html": "

这次原本只想给一个已经由 Nginx UI 管理的站点加上 HTTPS，最后却依次排查了\nNginx UI 启动、ACME CA、域名验证、DNS API 权限、证书文件和 Nginx 重载。

\n

最有价值的结论不是某一条“万能命令”，而是要把问题拆成四段：管理界面能否工作、CA\n能否创建订单、域名控制权能否验证、Nginx 最终是否加载了正确的证书。把这四件事混在\nNginx UI 的一个申请按钮里看，很容易在错误方向上反复尝试。

\n

本文保留这次排查的时间线，但域名、凭据和服务器信息均已替换为占位符。可直接执行的\n完整流程放在使用 acme.sh 为 Nginx UI 管理的站点配置 HTTPS。

\n

起点：先遇到的不是证书，而是 Nginx UI 启动​

\n

最初看到 Nginx UI 无法正常启动时，我先把它和证书问题联系到了一起。后来才意识到，\nNginx UI 进程、Nginx 进程和 ACME 签发是三条相互关联但可以独立验证的链路。

\n

排查顺序应该先回到最基础的状态：

\n
systemctl status nginx-ui --no-pager
journalctl -u nginx-ui -n 100 --no-pager
nginx -t
systemctl status nginx --no-pager
\n

只有 Nginx UI 和 Nginx 本身都稳定后，证书申请日志才有解释价值。否则一次界面上的失败，\n可能只是服务未启动、配置未加载或 Nginx 测试未通过，并不代表 CA 拒绝签发。

\n

第一次弯路：在 Nginx UI 里直接配置证书​

\n

服务恢复后，我尝试直接通过 Nginx UI 申请和配置证书。这条路径本身是受支持的，但在这次\n环境里，它同时引入了太多变量：

\n\n

这次对话中的日志先后指向不同环节。切换 CA 后错误表现会变化，但这并不能修复域名验证；\nDNS 页面能登录也不代表 API 凭据有修改记录的权限；浏览器能打开域名，也不代表 ACME\n验证节点能获得期望的 TXT 或 HTTP 响应。

\n

容易误读的端口​

\n

Nginx UI 的 HTTPChallengePort 是其后端在 HTTP-01 流程中使用的监听端口，当前文档中的\n默认值是 9180。但 Let’s Encrypt 的 HTTP-01 验证仍然只会从公网访问 80 端口。也就是说，\n仅确认 9180 在本机监听并不能证明验证链路成立，公网 80 端口还必须把\n/.well-known/acme-challenge/ 请求正确交给挑战处理程序。

\n

这也是直接配置时最容易出现的错觉：界面和后端都在运行，CA 却仍然无法验证域名。

\n

容易误读的“证书已存在”​

\n

另一个坑是文件形态。Nginx UI 的自动发现会扫描配置的 Nginx ssl 目录，并识别分别保存的\n证书链和私钥，例如 fullchain.pem 与 privkey.pem。把证书链和私钥拼成单个 PEM 文件，\n并不属于它的自动发现范围。

\n

因此，“服务器上已经有一个 PEM 文件”并不等于 Nginx UI 已经发现它，更不等于站点配置\n已经引用它。

\n

改变策略：把签发和部署拆开​

\n

继续在界面里同时调整 CA、挑战方式和 DNS 凭据只会让日志越来越难比较。我最后改用\nacme.sh 单独完成 DNS-01 签发，再把稳定的证书文件交给 Nginx UI 和 Nginx 使用。

\n

选择 DNS-01 的原因不是它天然优于 HTTP-01，而是这次环境中的公网 80 端口和转发链路并不\n适合作为唯一验证入口。DNS-01 直接通过 _acme-challenge.<DOMAIN> TXT 记录证明域名控制权，\n也支持通配符证书。

\n

在执行前，先确认权威 DNS，而不是根据域名注册商或曾经使用过的控制台猜测：

\n
dig NS example.com +short
dig TXT _acme-challenge.app.example.com +short
\n

然后只为实际的权威 DNS 提供商创建最小权限凭据。本次最终可工作的链路是：

\n
    \n
  1. acme.sh 向选定的 ACME CA 创建订单；
    2. \n
  2. DNS API 临时创建 _acme-challenge TXT 记录；
    3. \n
  3. CA 查询权威 DNS 并完成验证；
    4. \n
  4. acme.sh --install-cert 把证书链和私钥复制到 Nginx 的稳定目录；
    5. \n
  5. nginx -t 通过后重载 Nginx。
    6. \n
\n

CA 从 ZeroSSL 切换到 Let’s Encrypt 时，我明确写出了 --server letsencrypt。这一步只是\n选择 CA，不应被当成修复 DNS 权限或网络问题的方法。

\n

为什么没有直接引用 acme.sh 的内部文件​

\n

acme.sh 会在 ~/.acme.sh/ 下保存自己的状态和证书材料，但其官方说明明确不建议服务器\n直接引用这些内部文件。正确做法是使用 --install-cert 复制到生产路径，并配置重载命令：

\n
~/.acme.sh/acme.sh --install-cert -d app.example.com --ecc \\
  --key-file /etc/nginx/ssl/app.example.com/privkey.pem \\
  --fullchain-file /etc/nginx/ssl/app.example.com/fullchain.pem \\
  --reloadcmd \"nginx -t && systemctl reload nginx\"
\n

这样续期后会再次更新稳定路径，并在配置检查通过后重载 Nginx。若只复制一次文件，证书虽然\n会续期，线上服务却可能一直展示旧证书。

\n

最后如何确认真的成功​

\n

浏览器出现锁形图标只是最后一个信号。我把验证拆成了四层：

\n
dig A app.example.com +short
ss -lntp | rg ':(80|443)\\b'
nginx -t
openssl s_client -connect app.example.com:443 \\
  -servername app.example.com -showcerts </dev/null
\n

还要核对证书和私钥是否匹配。下面的公钥摘要应相同：

\n
openssl x509 -in /etc/nginx/ssl/app.example.com/fullchain.pem \\
  -pubkey -noout | openssl sha256
openssl pkey -in /etc/nginx/ssl/app.example.com/privkey.pem \\
  -pubout | openssl sha256
\n

最后执行一次不强制续期的定时任务检查，并查看下一次续期时间：

\n
~/.acme.sh/acme.sh --cron --home ~/.acme.sh
~/.acme.sh/acme.sh --info -d app.example.com --ecc
\n

这次踩坑留下的判断顺序​

\n

以后再遇到同类问题，我会按这个顺序处理：

\n
    \n
  1. 先确认 Nginx UI 与 Nginx 服务健康，避免把启动问题当成证书问题。
    2. \n
  2. 查权威 DNS，再选择 DNS API，不能根据注册商或控制台印象猜。
    3. \n
  3. 一次只改变一个变量；切换 CA 不会修复挑战验证。
    4. \n
  4. 区分“签发成功”“文件已部署”和“Nginx 已加载”三个状态。
    5. \n
  5. 使用稳定部署路径和可靠的 reloadcmd，把自动续期真正闭环。
    6. \n
\n

完整的无敏感信息操作清单和回滚方法见：

\n", "url": "https://blog.biulight.top/timeline/blog/nginx-ui-https-certificate", "title": "给 Nginx UI 配置 HTTPS：从界面申请失败到拆开证书签发链路", "summary": "这次原本只想给一个已经由 Nginx UI 管理的站点加上 HTTPS，最后却依次排查了", "date_modified": "2026-07-07T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Nginx UI", "HTTPS", "ACME", "Troubleshooting" ] }, { "id": "https://blog.biulight.top/timeline/blog/coredns-new-record-mdnsresponder-cache", "content_html": "

给自建的私有域名新增了一条 CoreDNS 记录，ping 却始终报\"无法解析主机\"，而同一个域名后缀下\n其他早就存在的记录一切正常。这次排查依次怀疑了 Surge、Proxifier，最后才发现是 macOS\nmDNSResponder 的陈旧缓存在作怪。

\n

本文保留这次排查的时间线，域名、内网地址和服务器信息均已替换为占位符。

\n

背景​

\n

设备已经通过 shine sys apply split-dns 把私有域名后缀交给自建 CoreDNS 解析,具体原理见\n使用 ZeroTier、CoreDNS 和 Shine 搭建异地私有域名网络。\n这次是往 CoreDNS 的 Corefile 里新增了一条 hosts 记录：

\n
hosts {
    10.20.30.10 nginx-ui.example.internal
    10.20.30.10 blog.example.internal   # 新加的
    ...
    fallthrough
}
\n

reload 插件会自动感知 Corefile 变化，理论上不需要重启容器。

\n

现象​

\n
❯ ping blog.example.internal
ping: cannot resolve blog.example.internal: Unknown host

❯ ping nginx-ui.example.internal
PING nginx-ui.example.internal (10.20.30.10): 56 data bytes
64 bytes from 10.20.30.10: icmp_seq=0 ttl=64 time=11.383 ms
\n

同一个域名后缀、同一台 CoreDNS、同一个目标 IP，新记录解析不出来，旧记录完全正常。这种\"只有\n新东西不行\"的现象,比单纯的\"DNS 全部失效\"更容易让人误判方向。

\n

先排除服务端​

\n

在下结论之前，先直接绕过本机的解析路径，对 CoreDNS 发一次权威查询：

\n
dig @10.20.30.10 blog.example.internal
\n

拿到的是正确、带 aa（authoritative answer）标志的应答。这一步很关键：它证明 CoreDNS 本身\n配置正确、hosts 记录也确实生效了，问题出在客户端到 CoreDNS 之间的某个环节，而不是服务端。

\n

第一个怀疑对象：Surge​

\n

scutil --dns 显示 split-dns 的域名专属 resolver 配置完全正确，指向 CoreDNS 地址；但\ndscacheutil -q host -a name blog.example.internal（真正走系统解析路径的检查方式）却什么\n都拿不到。同时 route -n get 10.20.30.10 显示去 CoreDNS 的路由走的是一个 feth 虚拟网卡，\n而这台机器上 Surge 的 Network Extension 处于 activated enabled 状态，很自然地怀疑是 Surge\n的 Enhanced Mode（TUN 模式）把 DNS 流量整体接管了。

\n

但这个方向被用户当场否掉：Surge 既没开系统代理，也没开 TUN 模式，只是用来暴露一个代理接口。\n后面证实这个怀疑确实是误判——feth 网卡另有来源，和 Surge 是否处于 Enhanced Mode 无关。

\n

第二个怀疑对象：Proxifier​

\n

同一台机器上还装了 Proxifier，它的系统扩展同样是 activated enabled。检查它当前生效的\nprofile，发现关键设置：

\n
<Resolve>
    <ViaProxy enabled=\"true\">
        <TryLocalDnsFirst enabled=\"false\"/>
    </ViaProxy>
    <ExclusionList ...>localhost;%SimpleHostnames%;%ComputerName%;*.local;</ExclusionList>
</Resolve>
\n

ViaProxy enabled=\"true\" 加 TryLocalDnsFirst enabled=\"false\" 意味着：只要域名没有命中\n排除列表，Proxifier 就不会走本地 DNS，而是尝试通过代理解析——代理服务器当然不认识私有域名。\n排除列表里只有 *.local，没有内网域名后缀，这个方向看起来很有说服力。

\n

第一次修改却改错了地方：把内网域名后缀加进了 RuleList 里某条规则的 Targets（那是连接\n路由规则，Direct/Proxy 二选一），而不是 Options → Resolve 里控制\"域名解析是否走代理\"的\nExclusionList——域名解析在连接路由匹配之前就已经失败，规则改了也没用。

\n

修正到正确的位置后仍然不行；干脆完全退出 Proxifier 应用再测试，问题依旧存在。到这一步，\nProxifier 也被排除了。

\n

真正的原因：mDNSResponder 的陈旧缓存​

\n

排除了两个代理工具之后，回到最基础的怀疑对象——本机 DNS 解析进程自身的缓存。

\n
dscacheutil -flushcache
\n

在近几个版本的 macOS 上，这条命令并不总能可靠地清掉 mDNSResponder 内部持有的解析结果，\n必须直接让守护进程重新加载：

\n
sudo killall -HUP mDNSResponder
\n

执行后立刻复测：

\n
❯ ping blog.example.internal
PING blog.example.internal (10.20.30.10): 56 data bytes
64 bytes from 10.20.30.10: icmp_seq=0 ttl=64 time=19.909 ms
64 bytes from 10.20.30.10: icmp_seq=1 ttl=64 time=11.723 ms

❯ dscacheutil -q host -a name blog.example.internal
name: blog.example.internal
ip_address: 10.20.30.10
\n

问题解决，和 Surge、Proxifier、CoreDNS 配置都没有关系。

\n

真正的原因是：blog.example.internal 是后加进 CoreDNS 的新记录，而 nginx-ui.example.internal\n这类记录加入的时间更早。大概率是在这条新记录刚加入、split-dns 还没有完全生效的窗口期内，\nmDNSResponder 已经对新名字做过一次失败查询并缓存了负面结果；而老记录当时早已缓存了正确\n结果，所以一直\"看起来没问题\"，制造了\"只有新东西解析不出来\"的假象，把排查方向一路带偏到了\n两个代理工具身上。

\n

这次排查留下的判断顺序​

\n

以后再遇到\"某个内网域名解析不出来，其他域名都正常\"，会按这个顺序处理：

\n
    \n
  1. 先用 dig @<DNS服务器IP> <域名> 直接查权威 DNS，确认是服务端问题还是客户端问题，\n不要一上来就怀疑代理软件。
    2. \n
  2. 拿同一个域名后缀下\"早就存在、一直正常\"的记录和\"新加的、解析不出来\"的记录做对比。如果\n真的是代理或路由层面的问题，两者应该同时失效；只有新记录失效，更可能是客户端缓存问题。
    3. \n
  3. dscacheutil -flushcache 不一定够用，sudo killall -HUP mDNSResponder 才是更可靠的\n强制刷新方式。
    4. \n
  4. 用 Proxifier 一类工具时，分清\"域名解析是否走代理\"（Resolve/ExclusionList）和\"连接走\nDirect 还是走代理\"（RuleList/Targets）是两个独立的配置面，改错地方不会生效，也不会报错，\n容易误以为\"这个方向也不对\"。
    5. \n
  5. 新增内网 DNS 记录后，如果客户端之前已经查询过这个域名并失败过，最好主动做一次\nsudo killall -HUP mDNSResponder，而不是假设 reload 插件生效后客户端会自动更新。
    6. \n
", "url": "https://blog.biulight.top/timeline/blog/coredns-new-record-mdnsresponder-cache", "title": "新增了一条 CoreDNS 记录却解析不出来：从怀疑 Surge、Proxifier 到重启 mDNSResponder", "summary": "给自建的私有域名新增了一条 CoreDNS 记录，ping 却始终报\"无法解析主机\"，而同一个域名后缀下", "date_modified": "2026-07-07T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "macOS", "CoreDNS", "DNS", "Troubleshooting" ] }, { "id": "https://blog.biulight.top/timeline/blog/terminal-proxy-no-proxy-zerotier", "content_html": "

最近在一台已经接入 ZeroTier 的设备上排查服务连通性，本来只是想用 curl 直接访问私有域名，结果请求却被本地 HTTP 代理接管了。

\n

如果你也在终端里设置了 HTTP_PROXY、HTTPS_PROXY，同时又依赖 ZeroTier 私有域名或 192.168.x.x 这一类局域网地址，最好顺手检查一下 NO_PROXY / no_proxy。否则 DNS 虽然能解析到内网目标，请求仍可能先进入本地代理链路。

\n

这类场景在结合 Shine 的 proxy shell 预设时尤其容易忽略，因为我们平时更关注“代理有没有打开”，不一定会第一时间想到“哪些地址本来就不该走代理”。

\n

背景​

\n

目标很简单：通过 ZeroTier 提供的私有网络和私有 DNS，直接访问一台内网服务。

\n

按预期，这条链路应该是：

\n
    \n
  1. 终端解析 <PRIVATE_HOST> 之类的私有域名。
    2. \n
  2. 系统把该域名交给私有 DNS。
    3. \n
  3. DNS 返回 ZeroTier 地址或局域网地址。
    4. \n
  4. curl 直接连向目标服务。
    5. \n
\n

但实际现象不是这样。

\n

现象​

\n

在已经启用终端代理的 shell 中执行：

\n
curl http://<PRIVATE_HOST>
curl http://192.168.0.10:8080
\n

请求没有直接访问目标，而是进入了本地 HTTP 代理。对某些代理软件来说，这会表现为请求被拦截、拒绝，或者在日志里出现一条本不该经过代理的内网访问记录。

\n

这时最容易误判成下面几类问题：

\n\n

但如果浏览器、其他客户端，或者关闭代理后的同一条命令能够访问成功，就该反过来检查当前 shell 的代理环境。

\n

原因​

\n

curl 这类命令行工具会读取当前终端中的代理变量，例如：

\n
env | rg '^(HTTP_PROXY|HTTPS_PROXY|NO_PROXY|http_proxy|https_proxy|no_proxy)='
\n

只要 HTTP_PROXY / HTTPS_PROXY 已设置，而 NO_PROXY / no_proxy 没有覆盖私有域名后缀和局域网地址段，这些请求仍会走代理。

\n

这也是 ZeroTier 场景里很容易忽略的一点：

\n\n

这三个环节缺一不可。前两项都正确时，最后仍可能卡在代理变量这一层。

\n

修复​

\n

如果你用 Shine 管理终端代理，推荐直接维护 PROXY_NO_PROXY，让 Shine 统一生成 NO_PROXY 和 no_proxy。

\n

先查看当前配置：

\n
shine env list
shine info shell/proxy
\n

然后把默认值和私有网络需要的排除项一起写进去。下面示例全部使用占位值：

\n
shine env set PROXY_NO_PROXY \\
  'localhost,127.0.0.1,::1,.home.example.internal,192.168.0.0/16'
\n

这里至少建议覆盖：

\n\n

修改后不要只停留在 env set。Shine 会先把已安装的 proxy 预设标记为可更新，还需要执行：

\n
shine update shell/proxy
shine upgrade shell/proxy
\n

如果你不是用 Shine 管理终端代理，本质上也一样：最终要确认当前 shell 里的 NO_PROXY / no_proxy 已经包含这些私有目标。

\n

验证​

\n

先确认当前 shell 中的代理变量已经变成预期值：

\n
shine info shell/proxy
env | rg '^(HTTP_PROXY|HTTPS_PROXY|NO_PROXY|http_proxy|https_proxy|no_proxy)='
\n

再分别验证私有域名和局域网地址：

\n
curl http://<PRIVATE_HOST>
curl http://192.168.0.10:8080
\n

如果修复生效，这两类请求应该直接访问目标，而不是继续进入本地代理。

\n

若你使用的是基于私有域名的 ZeroTier 解析链路，也可以顺手对照这篇原理说明：

\n\n

延伸建议​

\n

这个坑本质上不是 ZeroTier 独有问题，而是“终端代理”和“私有网络”叠在一起时的常见遗漏。

\n

如果你希望以后少踩一次，最简单的做法有两个：

\n
    \n
  1. 把私有域名后缀和常用内网地址段纳入 PROXY_NO_PROXY 的默认维护范围。
    2. \n
  2. 每次怀疑 ZeroTier 或私有 DNS 之前，先检查一眼当前 shell 的代理变量。
    3. \n
\n

如果你只想快速排查同类问题，可以直接看这篇排障文：

\n", "url": "https://blog.biulight.top/timeline/blog/terminal-proxy-no-proxy-zerotier", "title": "终端代理没有排除 ZeroTier 私有域名，结果请求被本地代理拦截", "summary": "最近在一台已经接入 ZeroTier 的设备上排查服务连通性，本来只是想用 curl 直接访问私有域名，结果请求却被本地 HTTP 代理接管了。", "date_modified": "2026-07-05T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Shine", "ZeroTier", "Proxy", "Troubleshooting" ] }, { "id": "https://blog.biulight.top/timeline/blog/2025/02/07/qnap-docker", "content_html": "

威联通 Docker 国内无法拉取镜像？

\n

背景​

\n

由于众所周知的原因，国内拉取 docker 镜像愈发可困难，网上现有的教程涉及 NAS 的极少，为了能愉快的使用 NAS，我进行了大量尝试，终于找到了可用的方法，顺手记录下，分享给各位苦苦挣扎的道友。

\n

常见的方案​

\n

现有环境下，想成功拉取镜像，无非使用魔法或者换国内镜像。

\n

使用代理​

\n
    \n
  1. 开启威联通 ssh 服务,并通过 ssh 连接到 QNAP
    2. \n
\n
# 远程登录
ssh -p 22 username@192.168.0.155
\n
提示

SSH 服务的默认端口是 22，上述命令是 用户通过 SSH 工具用账号（username）连接到服务器（192.168.0.155）的 22 端口

\n
    \n
  1. 增加 docker 的代理配置
    2. \n
\n
# 编辑配置文件
sudo vim /share/CACHEDEV1_DATA/.qpkg/container-station/etc/docker.json
\n

增加代理配置

\n
/share/CACHEDEV1_DATA/.qpkg/container-station/etc/docker.json
{
  // 新增配置
  \"proxies\": {
    \"http-proxy\": \"http://代理地址:端口\",
    \"https-proxy\": \"http://代理地址:端口\",
    \"no-proxy\": \"*.test.example.com,.example.org,127.0.0.0/8\"
  }
}
\n
提示

ssh 登录后，可以通过 which docker、whereis docker 查看 docker 所在位置

\n
    \n
  1. 重启 docker 服务
    2. \n
\n
sudo /etc/init.d/container-station.sh restart
\n
    \n
  1. 查看配置是否成功
    2. \n
\n
docker info
\n

如下图：\n\"代理设置成功\"

\n

完成上述设置后，你就可以愉快的拉取镜像了

\n

更换国内镜像源​

\n
\n

参考使用代理，增加镜像源配置

\n
\n

步骤 1、2 参考使用代理

\n
# 编辑配置文件
sudo vim /share/CACHEDEV1_DATA/.qpkg/container-station/etc/docker.json
\n

增加镜像源配置

\n
/share/CACHEDEV1_DATA/.qpkg/container-station/etc/docker.json
{
  // 新增配置
  \"registry-mirrors\": [
    \"https://mirror.ccs.tencentyun.com\",
    \"https://docker.mirrors.ustc.edu.cn\"
  ]
}
\n
信息

腾讯云镜像加速器地址：https://mirror.ccs.tencentyun.com

中国科学技术大学：https://docker.mirrors.ustc.edu.cn

Docker 官方镜像（中国区）镜像加速：https://registry.docker-cn.com

网易云镜像加速器地址：http://hub-mirror.c.163.com

南京大学镜像加速器地址：https://docker.nju.edu.cn

\n

剩余步骤参考使用代理

", "url": "https://blog.biulight.top/timeline/blog/2025/02/07/qnap-docker", "title": "拯救你的Docker", "summary": "威联通 Docker 国内无法拉取镜像？", "date_modified": "2025-02-07T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Linux", "Docker", "QNAP" ] }, { "id": "https://blog.biulight.top/timeline/blog/2025/02/05/deploy-by-github", "content_html": "

怎样通过 Github 自动交付前端编译产物？

\n

准备​

\n

一台阿里云 ubuntu 服务器

\n

实施​

\n

以 deploy 用户组下的 deploy001-timeline 用户,部署目录 /path/to/folder，部署工具 easingthemes/ssh-deploy@v2.2.11 为例

\n

新建部署用户，修改部署目录权限​

\n
提示

遵循权限最小化原则，创建 deploy001-timeline 用户，用于部署\n若已存在 deploy 用户组，跳过步骤 1，直接新建指定项目部署用户

\n
# 检查指定xxx用户组是否存在
cat /etc/group | grep xxx
\n
    \n
  1. 创建用户组
    2. \n
\n
sudo addgroup deploy
\n
    \n
  1. 创建用户
    2. \n
\n
sudo adduser --ingroup deploy deploy001-timeline
\n
    \n
  1. 指定部署目录的归属
    2. \n
\n
sudo chown deploy001-timeline:deploy /path/to/folder
\n
    \n
  1. 更新目录权限
    2. \n
\n
sudo chmod 755 /path/to/folder
\n

配置部署工具​

\n

以 easingthemes/ssh-deploy@v2.2.11 为例

\n
提示

easingthemes/ssh-deploy使用手册

\n

服务器侧​

\n
提示

使用 ssh 登录服务器，需要使用一组秘钥对，其中公钥设置到服务器 ~/.ssh/authorized_keys 文件中，私钥设置在客户端

\n
    \n
  1. 登录新创建的用户
    2. \n
\n
su deploy001-timeline
\n
    \n
  1. 生成非对称密钥
    2. \n
\n
ssh-keygen -m PEM -t rsa -b 4096 -f deploy001-timeline -C \"deploy001-timeline\"
\n
    \n
  1. 把公钥粘贴到 authorized_keys 文件中
    2. \n
\n
# 查看公钥，复制输出到终端的结果
cat deploy001-timeline.pub
# 编辑 authorized_keys 文件，并把复制的结果粘贴到此文件
vim ~/.ssh/authorized_keys
\n
~/.ssh/authorized_keys
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDcGxPtreCc5bBbaN7jIRuVuTQkC0Mp6VxnyC5sQKG1IZwSL5agL3Zdbu3YVzx0rSU33XZZj5lWp0AAz4ABQGhAU6iIgDNjRmhyuLG4VOS3Gas21Si1lK4Dm/D0lBA//zFmDBTwa9sAEl39rJQCQYL3n2prMrlC2k8m93RGLFmgxWDcb2D+LGgi43bgR4TXvJD6dZa7xfIldsQL5SQpCzEMX8uDDlnnsus99AqmmMzUenW6I25G2ApwgUY/Toj/scCGeHRb7PmGK0AwjqBr9siiIRNi0DpX4JbYPqLPn0IciC70RNLs2tOEFV1BwP50gmF5eDD4tI7NOLaI4HvkesYy9xF6qBtNJOfALgu7Dt+s5g5izXg2pfb/RKJw2WEj56hLI2NIOr1CgZRJH6Yq2xlP1SKlo3GwkzT/NhnhiO1NFy/FKFj/sYmn4/SM92QM2OmruPDAU6JUHUT9P7m/bhlAxo5xrzMqH8v9c4acxUGz5s87j8eNcNfaIuzMQOG+jzEOqqdWI4uLeTPHrm4pSuZUuse7IenTN3Wx1MD4CfjyZZZIWR6Xv+f7MJ0CpbvpZ7E4MjenLfb8g/upl2L1kv3Lz/UUbL4n38DCY113wkJY5x6T54ckqHUmhirsL2SCHb71VAtxUhEByCTBdPEN18Hh+QOKKTp4rmJYjNrvm4E5yw== deploy001-timeline
\n
提示

vim 是 linux 常用的终端编辑器，常见命令如下

    \n
  1. :wq 保存并退出
    2. \n
  2. i 进入输入视图
    3. \n
\n

Github 配置​

\n

配置 secrets ，在 workflow 中使用

\n
提示

配置位置如下图所示\n\"配置位置参考图\"

\n
    \n
  1. 新增 ALY_USER，如下
    2. \n
\n
deploy001-timeline
\n
    \n
  1. 新增 ALY_HOST，如下
    2. \n
\n
192.168.0.155
\n
    \n
  1. 新增 ALY_SSH_TOKEN，如下
    2. \n
\n
-----BEGIN RSA PRIVATE KEY-----
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
-----END RSA PRIVATE KEY-----
\n
提示
\n

项目 workflow 配置​

\n
提示

配置文件配置在项目中，通常写在 .github/workflows 目录下

\n

example:

\n
.github/workflows/deploy.yml
name: Deployment
# 触发脚本的条件，develop分支push代码的时候
on:
  push:
    branches:
      - release
# 要执行的任务
jobs:
  # 任务名称
  build:
    # runs-on 指定job任务运行所需要的虚拟机环境（必填）
    # runs-on: self-hosted
    runs-on: ubuntu-latest
    # 任务步骤
    steps:
      # 获取源码
      - name: pull code
        # 使用action库  actions/checkout获取源码
        uses: actions/checkout@v3
      # 安装node
      - name: create build environments
        # 使用action库 actions/setup-node 安装node
        uses: actions/setup-node@v3
        with:
          node-version: 18.20.4
      # 安装依赖
      - name: install
        run: npm install
      # 打包
      - name: build
        run: npm run build
      - name: Upload static files as artifact
        id: deployment
        uses: actions/upload-pages-artifact@v3 # or specific \"vX.X.X\" version tag for this action
        with:
          path: build/
      # 上传打包文件到远程服务器
      - name: ssh deploy
        uses: easingthemes/ssh-deploy@v2.2.11
        env:
          REMOTE_USER: ${{secrets.ALY_USER}}
          REMOTE_HOST: ${{secrets.ALY_HOST}}
          REMOTE_PORT: \"22\"
          ARGS: \"-rltgoDzvO --delete\"
          SSH_PRIVATE_KEY: ${{secrets.ALY_SSH_TOKEN}}
          # 要上传文件所在目录
          SOURCE: \"build/*\"
          # 远程服务器目标路径
          TARGET: \"/var/www/timeline\"
\n

补充​

\n

NGINX 配置​

\n

以访问 http://blog.biulight.cn/timeline 能显示 /var/www/timeline 目录内容为例

\n
提示
    \n
  1. 通常，Nginx 的虚拟主机配置位于/etc/nginx/sites-available/目录下。如果已经有针对timeline的配置文件，可以直接编辑它；否则，创建一个新的配置文件。
    2. \n
  2. 启用配置文件，需要在 /etc/nginx/sites-enabled/目录下有对应配置文件的映射。
    3. \n
\n
    \n
  1. 新增配置文件
    2. \n
\n
/etc/nginx/sites-available/timeline
server {
    listen 80;
    server_name blog.biulight.cn;

    # 映射/timeline到指定目录
    location /timeline {
        alias /var/www/timeline;
        index index.html index.htm;
    }
}
\n
    \n
  1. 启用配置文件
    2. \n
\n
# 建立软连接，启用新增的配置文件
ln -s /etc/nginx/sites-available/timeline /etc/nginx/sites-enabled/timeline
\n
    \n
  1. 测试配置文件
    2. \n
\n
# 修改完配置后，运行以下命令检查语法是否正确
sudo nginx -t
\n
    \n
  1. 重新加载 Nginx 服务
    2. \n
\n
# 如果测试通过，重新加载Nginx以应用更改：
sudo systemctl reload nginx
\n

使用 Let's Encrypt 证书​

\n
提示

ubuntu 安装查看certbot官方文档

\n

使用certbot自动生成证书

\n
sudo certbot --nginx
", "url": "https://blog.biulight.top/timeline/blog/2025/02/05/deploy-by-github", "title": "使用Github自动交付前端制品", "summary": "怎样通过 Github 自动交付前端编译产物？", "date_modified": "2025-02-05T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Linux", "Ubuntu", "Deploy", "GitHub", "CI/CD" ] }, { "id": "https://blog.biulight.top/timeline/blog/2025/02/04/ubuntu-install-neovim", "content_html": "

Ubuntu 怎样安装指定版本的 Neovim?

\n

背景​

\n

由于 apt 中只有 Neovim(v0.72)的安装包。想使用新版需要自己安装

\n
\n

以 v0.9.5 版本为例

\n
\n

方案一​

\n
    \n
  1. 去 Github 上查看指定版本的压缩包,并下载
    2. \n
\n
sudo wget https://github.com/neovim/neovim/releases/download/v0.9.5/nvim-linux64.tar.gz
\n
    \n
  1. 解压缩 nvim-linux64 至 /opt 目录
    2. \n
\n
sudo tar -C /opt -xzf nvim-linux64.tar.gz
\n
    \n
  1. add this to your shell config (~/.bashrc, ~/.zshrc, ...):
    2. \n
\n
export PATH=\"$PATH:/opt/nvim-linux64/bin\"
\n
    \n
  1. reload shell config
    2. \n
\n
source ~/.bashrc
\n

方案二​

\n

使用 snap 包管理工具安装

\n
sudo snap install nvim --classisc
", "url": "https://blog.biulight.top/timeline/blog/2025/02/04/ubuntu-install-neovim", "title": "Install Neovim", "summary": "Ubuntu 怎样安装指定版本的 Neovim?", "date_modified": "2025-02-04T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Linux", "Ubuntu", "Neovim" ] }, { "id": "https://blog.biulight.top/timeline/blog/2024/08/10/document.title", "content_html": "

埋点监控 SDK ENTER 事件怎样获取到页面标题？

\n

背景​

\n

使用 window.onload、hashchange 事件获取 document.title 时，某些场景出现异常，值为空

\n

分析​

\n

单页面应用，document.title 存在异步设置的场景（如页面是后管配置的，需要等接口返回页面标题）

\n

方案​

\n

场景一：多页面应用，title 写在 html 文件里；​

\n

window.onload 事件可以正常获取到页面标题

\n

场景二：单页面应用，title 在页面初始化后设置；​

\n
\n

借助 MutationObserver 观察 title 元素更新

\n
\n
function watchForTitleChanges(callback, type) {
  let ele = document.getElementsByTagName(\"title\")?.[0];
  if (!ele) {
    ele = document.createElement(\"title\");
    document.head.appendChild(ele);
  }
  let previousTitle = document.title;
  const observer = new MutationObserver((mutationList, observer) => {
    const title = document.title;
    if (previousTitle !== title) {
      previousTitle = title;
      callback?.(title);
      if (type === \"once\") observer.disconnect();
    }
  });

  observer.observe(ele, { childList: true });
  // 非仅监听一次更新时，返回取消监听函数
  if (type !== \"once\") return observer.disconnect;
}
\n

完美实现如下：

\n
// 页面初次加载时，在 load 事件中注册 watch
window.addEventListener(\"load\", () => {
  watchForTitleChanges((title) => {
    console.log(\"title发生了变化\", title);
  }, \"once\");
});

// 路由切换时，在 hashchange 事件中注册 watch
window.addEventListener(\"hashchange\", () => {
  watchForTitleChanges((title) => {
    console.log(\"title发生了变化\", title);
  }, \"once\");
});
", "url": "https://blog.biulight.top/timeline/blog/2024/08/10/document.title", "title": "Watch document.title", "summary": "埋点监控 SDK ENTER 事件怎样获取到页面标题？", "date_modified": "2024-08-10T00:00:00.000Z", "author": { "name": "feilx", "url": "https://github.com/biulight" }, "tags": [ "Web", "Supervisory control" ] } ] }