YYQ 的知识库

AI 前端 UI 设计：从零设计方向到落地工作流

Wed, 23 Sep 2026 00:00:00 GMT

AI 前端 UI 设计：从零设计方向到落地工作流#

更新日期：2026-09-23
适用场景：你知道产品/功能要做什么，但完全没有 UI 设计方向；希望 Claude Code、Codex、v0、Figma Make 等工具先帮你找到设计方向，再生成一套美观、统一、可维护的前端页面。
核心原则：不要让 AI 在没有视觉依据的情况下直接写 UI。先研究 → 再定设计系统 → 再实现 → 最后视觉验收。

1. 最终推荐工作流#

如果当前只有一句：

“我要做一个技术知识库 / SaaS 后台 / 个人网站，但是不知道页面该长什么样。”

不要直接让 Claude Code 或 Codex 开始写 CSS。

推荐流程：

1
产品需求
2
  │
3
  ▼
4
理解产品类型 / 用户 / 主要任务
5
  │
6
  ▼
7
设计探索
8
  ├── Google Stitch
9
  ├── Refero Styles
10
  ├── Refero MCP
11
  ├── Landbook
12
  ├── Mobbin
13
  └── UI/UX Pro Max
14
  │
15
  ▼
16
整理 3 个明显不同的视觉方向
17
  │
18
  ▼
19
选择一个方向
20
  │
21
  ▼
22
形成 DESIGN.md
23
  │
24
  ▼
25
Anthropic frontend-design
26
  +
27
21st.dev / shadcn / Aceternity
28
  │
29
  ▼
30
先实现 1 个代表页面
31
  │
32
  ▼
33
真实浏览器截图
34
  │
35
  ▼
36
Impeccable critique
37
  │
38
  ▼
39
Impeccable audit
40
  │
41
  ▼
42
Impeccable polish
43
  │
44
  ▼
45
确认后再推广到全部页面

展开收起

最重要的是：

1
错误：
2
需求 → “帮我做漂亮一点” → AI 直接写代码
3

4
正确：
5
需求 → 找参考 → 定设计方向 → DESIGN.md → 实现 → 截图审查 → Polish

2. DESIGN.md：整套工作流的核心中间产物#

2.1 它是什么#

DESIGN.md 可以理解成：

给 AI Coding Agent 看的设计系统 README。

里面不是业务代码，而是明确告诉 Claude Code / Codex：

页面应该是什么气质
主色和辅助色是什么
字体怎么选
标题层级怎么处理
页面最大宽度
间距体系
圆角大小
Card 是否应该大量使用
Border / Shadow 怎么使用
Button / Input / Navigation 的视觉规则
动效原则
Mobile 怎么处理
哪些设计明确禁止

Google Stitch 已将 DESIGN.md 作为跨设计/编码工具共享设计规则的一种格式；Refero Styles 和 Impeccable 也围绕它提供实际工作流。

2.2 建议项目结构#

1
project/
2
├─ DESIGN.md
3
├─ PRODUCT.md                 # 如果使用 Impeccable
4
├─ AGENTS.md
5
├─ CLAUDE.md
6
├─ src/
7
└─ ...

2.3 一个简单例子#

1
# Design System
2

3
## Overview
4

5
这是一个面向开发者的个人技术知识库。
6

7
视觉方向：
8
- content-first
9
- calm
10
- technical
11
- editorial
12
- high readability
13
- restrained decoration
14

15
拒绝：
16
- 紫蓝渐变
17
- 大量 Glassmorphism
18
- 页面全部 Card 化
19
- 巨大圆角
20
- 无意义发光
21
- 过度动画
22

23
## Colors
24

25
Background: #F7F6F2
26
Surface: #FFFFFF
27
Text Primary: #1D1D1F
28
Text Secondary: #686868
29
Border: #E4E1DA
30
Accent: #C65D32
31

32
## Typography
33

34
Article:
35
- Serif / readable long-form font
36

37
UI:
38
- Clean Sans Serif
39

40
Code:
41
- Monospace
42

43
## Layout
44

45
Article max-width: 760px
46
App shell max-width: 1440px
47
Sidebar: 260px
48

49
## Shapes
50

51
Buttons: 6px
52
Inputs: 6px
53
Cards: 8px
54
Avoid 16px+ radius unless there is a clear reason.
55

56
## Components
57

58
Article cards should behave like list rows rather than floating cards.
59

60
## Do's and Don'ts
61

62
DO:
63
- prioritize reading
64
- use whitespace for hierarchy
65
- maintain visible information density
66

67
DON'T:
68
- wrap every section in a card
69
- add badges only for decoration

展开收起

2.4 实际使用#

把 DESIGN.md 放进项目根目录后，对 Claude Code / Codex 说：

1
开始 UI 工作之前先完整读取 DESIGN.md。
2

3
DESIGN.md 是本项目视觉设计的 Source of Truth。
4

5
实现页面时必须遵循其中：
6
- Typography
7
- Color
8
- Spacing
9
- Layout
10
- Component
11
- Motion
12
- Anti-pattern
13

14
如果当前代码和 DESIGN.md 冲突：
15
先指出冲突，不要自行覆盖 DESIGN.md。

展开收起

3. Google Stitch：完全没方向时先探索设计#

官方：

3.1 它解决什么问题#

Stitch 最适合：

“我连自己喜欢什么风格都不知道。”

它不是单纯的“文字 → 一个页面”。

比较理想的使用方式是：

1
业务目标
2
↓
3
让 Stitch 同时探索不同视觉方向
4
↓
5
比较
6
↓
7
继续迭代其中一个
8
↓
9
形成 DESIGN.md
10
↓
11
把设计规则交给 Codex / Claude Code

3.2 实际模拟：做一个技术知识库#

你不要输入：

1
做一个漂亮的个人知识库。

建议输入：

1
我要设计一个个人技术知识库。
2

3
主要内容：
4
- Java 后端
5
- AI Coding
6
- Windows
7
- Linux / Server
8
- 网络与代理
9
- 开发工具
10

11
用户主要行为：
12
1. 浏览分类
13
2. 搜索文章
14
3. 阅读长篇技术文档
15
4. 查看代码块
16
5. 在不同技术主题之间跳转
17

18
目前我没有视觉方向。
19

20
暂时不要收敛成一个方案。
21

22
请探索 3 个明显不同的设计方向：
23

24
A. 技术工具 / Developer Tool 风格
25
B. Editorial / 长文阅读风格
26
C. 现代 Product / SaaS 风格
27

28
三个方向必须在：
29
Typography
30
Color
31
Navigation
32
Density
33
Surface
34
Article Layout
35
Code Block
36
Spacing
37
Motion
38

39
方面有明显区别。
40

41
避免：
42
- 紫蓝渐变
43
- 大量卡片
44
- Glassmorphism
45
- 巨型圆角
46
- 典型 AI SaaS Landing Page
47

48
先做视觉探索，不要急着完成最终页面。

展开收起

你会做什么#

你只需要比较：

1
A：看着像开发工具，我喜欢
2
B：阅读体验舒服，我喜欢
3
C：太像 SaaS，我不喜欢

然后继续：

1
以 B 为主。
2

3
保留 B 的：
4
- Typography
5
- 内容布局
6
- 阅读宽度
7
- 页面留白
8

9
加入 A 的：
10
- 左侧导航
11
- 搜索体验
12
- Code Block
13
- 技术感细节
14

15
重新整理成一个统一方向。

展开收起

最后：

1
请将目前确定的视觉规则整理为 DESIGN.md。
2
要求能够直接提供给 Claude Code / Codex 使用。

最适合使用 Stitch 的时候#

新项目
完全没设计方向
想同时比较多个方向
想通过视觉结果而不是文字描述挑风格
想最后输出 DESIGN.md

4. Refero Styles：不知道目标网站时如何找风格#

官网：

https://styles.refero.design/

DESIGN.md 示例：

https://styles.refero.design/ai-agents/design-md-examples

4.1 最容易误解的地方#

Refero Styles 不是必须先知道某个网站名称才可以使用。

在完全没方向时，不应该先搜：

1
Linear
2
Notion
3
Stripe

而应该先按以下几个维度找：

产品类型#

1
documentation
2
developer tools
3
SaaS
4
dashboard
5
analytics
6
knowledge base
7
portfolio
8
blog
9
AI startup
10
productivity
11
finance

页面类型#

1
landing page
2
docs
3
dashboard
4
settings
5
pricing
6
article
7
editorial
8
onboarding
9
authentication
10
search

视觉气质#

1
minimal technical
2
warm editorial
3
quiet
4
premium
5
monochrome
6
dark technical
7
clean SaaS
8
soft
9
playful
10
brutalist
11
high contrast
12
warm paper

Typography / Color#

1
serif editorial
2
monospace technical
3
warm cream
4
black and white
5
dark blue
6
earth tones
7
high contrast typography

4.2 实际模拟：完全不知道网站目标#

假设你要做：

个人技术知识库。

第一轮搜索#

先不要带品牌名。

1
documentation
2
developer tools
3
editorial
4
content rich
5
knowledge base

先观察你更容易被哪种视觉类型吸引。

假设结果显示你明显喜欢：

Warm paper
Serif title
Clean navigation
高阅读性
少 Card

那么进入第二轮。

第二轮搜索#

1
warm editorial
2
editorial tech
3
technical journal
4
warm paper
5
minimal editorial

第三轮收敛#

假设最终看到三个喜欢的 Design：

1
A：Warm Editorial
2
B：Technical Journal
3
C：Minimal Documentation

这时候不要问：

哪个品牌最牛？

而应该比较：

1
A 的 Typography 最喜欢
2
B 的导航最喜欢
3
C 的代码块和文档结构最喜欢

然后把三者交给 Agent：

1
我选择了 3 个 Refero Styles 参考。
2

3
参考 A：
4
主要借鉴 Typography、文章阅读感。
5

6
参考 B：
7
主要借鉴 Sidebar、页面层级。
8

9
参考 C：
10
主要借鉴 Code Block、Documentation Layout。
11

12
不要复制任何网站。
13

14
请抽象这些参考共同适合当前项目的规则，
15
形成一套新的 DESIGN.md。
16

17
如果规则冲突：
18
优先级为：
19
1. 阅读体验
20
2. 信息层级
21
3. 技术感
22
4. 装饰性

展开收起

4.3 找到一个喜欢的 DESIGN.md 后怎么用#

假设 Refero Styles 某个页面提供 DESIGN.md。

复制到项目：

1
DESIGN-REFERENCE.md

不要直接说：

1
照着它复制。

推荐：

1
读取 DESIGN-REFERENCE.md。
2

3
这是视觉参考，不是需要复制的网站。
4

5
先分析其中：
6
- Color
7
- Typography
8
- Spacing
9
- Layout
10
- Surface
11
- Border
12
- Shadow
13
- Radius
14
- Navigation
15
- Content hierarchy
16

17
结合当前产品实际需求，
18
重新生成本项目自己的 DESIGN.md。
19

20
允许继承其设计语言，
21
禁止复制：
22
- 品牌
23
- 文案
24
- Logo
25
- 独特业务组件
26
- 页面内容

展开收起

4.4 最适合 Refero Styles 的时候#

不知道具体网站
但可以通过“看图”判断喜欢不喜欢
想得到具体 DESIGN.md，而不是一句“高级、现代”
希望 Claude/Codex 有明确的 Typography / Color / Spacing 参考

5. Refero MCP + Refero Skill：让 Agent 自动研究真实产品#

官网：

https://refero.design/mcp

Refero Skill 官方安装方式：

Terminal window

1
npx skills add https://github.com/referodesign/refero_skill

MCP 当前属于 Refero Pro 能力。首次调用会进行浏览器授权，之后 Agent 可以直接搜索 Refero 的真实产品页面与 Flow。

5.1 它和 Refero Styles 的区别#

Refero Styles#

你自己：

1
搜索 → 看 → 选 → 给 AI

Refero MCP#

Agent：

1
理解需求
2
↓
3
自己搜索真实 UI
4
↓
5
比较多个产品
6
↓
7
提取模式
8
↓
9
设计

更适合 Claude Code / Codex 工作流。

5.2 实际模拟：让 Agent 自己找参考#

对 Claude Code / Codex：

1
当前项目没有明确 UI 方向。
2

3
禁止直接写页面。
4

5
先使用 Refero 做设计研究。
6

7
项目类型：
8
个人技术知识库。
9

10
重点页面：
11
- 首页
12
- 分类页
13
- 文章详情
14
- 搜索
15
- 移动端文章阅读
16

17
研究任务：
18

19
1. 搜索真实 Documentation / Developer Tool / Knowledge Base 产品。
20
2. 至少分析 10 个相关页面。
21
3. 不要只分析 Landing Page。
22
4. 优先查看：
23
   - Sidebar
24
   - Article layout
25
   - Search
26
   - Table of contents
27
   - Code blocks
28
   - Mobile navigation
29
5. 提取共同模式。
30
6. 再提出 3 个视觉方向。
31

32
暂时不要修改代码。

展开收起

第二轮#

1
三个方向中我选择方向 B。
2

3
继续使用 Refero 搜索与方向 B 最接近的真实产品页面。
4

5
重点验证：
6
- 内容宽度
7
- Sidebar 密度
8
- Typography
9
- Code block
10
- Search
11
- Article navigation
12

13
不要复制某一个产品，
14
而是从多个参考中归纳设计规律。
15

16
完成后生成 DESIGN.md。

展开收起

5.3 MCP 的最大价值#

普通 AI：

1
“Settings 页面应该怎么设计？”
2
→ 根据训练记忆想象

Refero MCP：

1
“Settings 页面应该怎么设计？”
2
→ 搜真实产品
3
→ 看布局
4
→ 看信息结构
5
→ 比较
6
→ 再设计

所以它更像：

给 Coding Agent 增加一个 UI 研究员。

6. Anthropic frontend-design：Claude 官方前端设计 Skill#

官方仓库：

https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design

Skill：

https://github.com/anthropics/skills/tree/main/skills/frontend-design

当前 Claude Code 官方插件仓库中也存在 frontend-design。

常见安装方式：

1
/plugin install frontend-design@claude-plugins-official

如果当前 Claude Code 版本 / Plugin 配置存在问题，优先查看官方 claude-plugins-official 和本机 /plugin 列表，不要使用网络上较旧的 marketplace 名称。

6.1 它干什么#

它不是一个组件库。

它主要改变 Claude 在设计 UI 时的决策方式：

1
普通 Claude
2
→ 安全
3
→ 常规
4
→ AI SaaS
5
→ Inter
6
→ 蓝紫渐变
7
→ Card
8

9
frontend-design
10
→ 先决定明确 aesthetic direction
11
→ Typography
12
→ Color
13
→ Composition
14
→ Motion
15
→ Visual details

展开收起

6.2 不推荐这样用#

1
帮我设计一个后台。

虽然会触发 Skill，但是你仍然把太多设计选择留给了模型。

6.3 推荐实际用法#

1
使用 frontend-design skill。
2

3
这是一个新的技术知识库项目。
4

5
先不要实现。
6

7
读取：
8
- PRODUCT.md
9
- DESIGN.md
10
- 当前页面代码
11

12
先总结：
13
1. 产品是什么
14
2. 用户主要任务
15
3. 当前视觉方向
16
4. 当前 DESIGN.md 最重要的 10 条约束
17

18
然后设计 Article Detail 页面。
19

20
要求：
21
- DESIGN.md 是视觉 Source of Truth
22
- 内容阅读优先
23
- 不要为了视觉效果降低信息密度
24
- 不要引入与 DESIGN.md 冲突的新颜色
25
- 不要自行换 Typography
26
- 不要添加无意义 Card / Badge / Gradient
27

28
先给页面结构方案，
29
确认结构合理后再实现。

展开收起

6.4 完全没有 DESIGN.md 时#

1
使用 frontend-design skill。
2

3
当前项目没有 DESIGN.md，也没有确定的 UI 方向。
4

5
暂时不要写代码。
6

7
请根据：
8
- 产品属性
9
- 目标用户
10
- 页面任务
11
- 内容密度
12

13
提出 3 个明显不同的视觉方向。
14

15
三个方向不能只是换颜色。
16

17
每个方向分别定义：
18
- Design philosophy
19
- Typography
20
- Color
21
- Layout
22
- Density
23
- Navigation
24
- Surface
25
- Radius
26
- Shadow
27
- Motion
28
- Anti-pattern
29

30
完成后等待选择。

展开收起

7. Impeccable：设计审查、Polish 与去 AI 味#

GitHub：

https://github.com/pbakaus/impeccable

官网：

https://impeccable.style/

当前推荐安装：

Terminal window

1
npx impeccable install

它可以检测 Claude、Codex、Cursor 等不同环境，并安装对应 Skill / Hook。

Codex 中通常通过 Skills 使用，例如：

1
$impeccable

Claude Code 中使用：

1
/impeccable <command>

7.1 重要命令#

1
/impeccable init
2
/impeccable craft
3
/impeccable shape
4
/impeccable document
5
/impeccable critique
6
/impeccable audit
7
/impeccable polish
8
/impeccable typeset
9
/impeccable layout
10
/impeccable colorize
11
/impeccable animate
12
/impeccable harden
13
/impeccable quieter
14
/impeccable bolder
15
/impeccable distill

展开收起

含义#

1
init
2
→ 初始化产品上下文，形成 PRODUCT.md
3

4
shape
5
→ 写代码前规划 UX/UI
6

7
document
8
→ 从现有实现整理 DESIGN.md
9

10
critique
11
→ 从设计角度批评当前页面
12

13
audit
14
→ 无障碍、响应式、性能等质量检查
15

16
polish
17
→ 最终设计打磨

展开收起

7.2 最适合你的使用方式#

不要把 Impeccable 当：

“一键把丑页面变漂亮。”

最好当：

设计 QA + 第二个设计师。

实际工作流#

1
/impeccable init

接着完成一个页面。

然后：

1
/impeccable critique article page

让它找：

hierarchy
typography
spacing
information density
visual balance
generic AI patterns

修复后：

1
/impeccable audit article page

检查：

accessibility
responsive
interaction state
overflow
performance

最后：

1
/impeccable polish article page

7.3 实际模拟 Prompt#

即使不用 slash command，也可以这样表达：

1
使用 Impeccable 对当前首页做 critique。
2

3
暂时不要修改代码。
4

5
从以下维度逐项检查：
6
- 页面视觉焦点
7
- Typography hierarchy
8
- Layout rhythm
9
- Spacing
10
- Alignment
11
- Color
12
- Contrast
13
- Information density
14
- Component repetition
15
- Card nesting
16
- Radius
17
- Shadow
18
- Decorative elements
19
- Mobile
20
- AI-generated UI patterns
21

22
把问题按：
23
P0 / P1 / P2
24

25
分级。
26

27
每个问题说明：
28
1. 在哪里
29
2. 为什么有问题
30
3. 应该怎么改
31

32
先只输出审查报告。

展开收起

之后：

1
根据刚才 critique 的 P0/P1 问题做一次集中修复。
2

3
不要借机整体重构页面。
4
不要改变已经确认的 DESIGN.md。

最后：

1
/impeccable polish

8. 21st.dev MCP / CLI：搜索真实组件而不是让 AI 瞎造#

官网：

https://21st.dev/

Agent / MCP：

https://21st.dev/mcp

它的核心思想：

Agent 不需要每次从模型记忆中重新发明 Pricing、Hero、Navbar、Dialog、Settings。

可以直接：

Terminal window

1
21st search "pricing table"

或者生成多个候选：

Terminal window

1
21st generate "a pricing table" --variants 3

8.1 实际模拟：Dashboard#

对 Agent：

1
不要自己从零设计 Dashboard Summary Cards。
2

3
使用 21st 搜索现有高质量组件。
4

5
需求：
6
- React
7
- Tailwind
8
- 不要大面积 Gradient
9
- 不要 Glassmorphism
10
- Radius <= 10px
11
- Desktop 信息密度中高
12
- 支持 Dark Mode
13
- Hover 要克制
14

15
先搜索候选。
16

17
给我 3 个方向，
18
暂时不要安装。

展开收起

或者 CLI：

Terminal window

1
21st search "analytics dashboard cards"

8.2 确认后再安装 / 使用#

1
选择候选 2。
2

3
安装以后不要原样使用。
4

5
请根据 DESIGN.md 修改：
6
- Color
7
- Typography
8
- Radius
9
- Border
10
- Spacing
11
- Interaction
12

13
最终效果必须属于我们自己的设计系统。

8.3 21st 特别适合做什么#

1
Hero
2
Pricing
3
Dashboard card
4
Navbar
5
Settings panel
6
Data visualization container
7
CTA
8
Testimonials
9
Feature section
10
Command menu

8.4 一个很好的探索命令#

自然语言：

1
show me three directions for this page

这是正确顺序：

1
先看三个方向
2
→ 再选
3
→ 再 Build

而不是：

1
直接 Build
2
→ 不喜欢
3
→ 重写
4
→ 又不喜欢

9. UI/UX Pro Max：自动生成设计系统候选#

GitHub：

https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

官网：

https://uupm.cc

当前 Skill 数据包括大量：

UI styles
Color palettes
Font pairings
UX guidelines
Chart types
Tech stacks

9.1 安装#

Claude：

Terminal window

1
npx ui-ux-pro-max-cli init --ai claude

Codex：

Terminal window

1
npx ui-ux-pro-max-cli init --ai codex

9.2 最适合做什么#

它非常适合：

从产品描述推导设计系统候选。

例如：

1
knowledge base
2
developer docs
3
technical editorial

让它在自己的设计数据库里找：

1
Style
2
Color
3
Typography
4
Effects
5
UX rules

9.3 实际模拟#

对 Agent：

1
使用 UI/UX Pro Max。
2

3
项目：
4
个人技术知识库。
5

6
关键词：
7
developer documentation
8
technical editorial
9
content-first
10
calm
11
high readability
12

13
请先生成 design system。
14

15
不要实现页面。
16

17
输出：
18
- 推荐 Style
19
- Color palette
20
- Font pairing
21
- Layout
22
- Density
23
- Effects
24
- Anti-patterns

展开收起

它内部的新项目工作流会使用 --design-system。

手动执行示意：

Terminal window

1
python "<skill-path>/scripts/search.py" \
2
  "developer documentation technical editorial" \
3
  --design-system \
4
  -p "Personal Knowledge Base"

如果想更大胆：

1
variance = 8

如果想低动效：

1
motion = 3

如果是 Dashboard：

1
density = 8

例如：

Terminal window

1
python "<skill-path>/scripts/search.py" \
2
  "internal analytics dashboard" \
3
  --design-system \
4
  --variance 7 \
5
  --motion 4 \
6
  --density 8 \
7
  -p "Ops Console"

9.4 正确定位#

推荐：

1
UI/UX Pro Max
2
→ 设计知识 / 候选 Design System

不要：

1
UI/UX Pro Max
2
→ 无脑把已有项目全部重构

如果已经有成熟的 DESIGN.md：

DESIGN.md 的优先级应该高于新生成的候选风格。

10. Figma Make：用可视化方式探索多个方案#

官网：

https://www.figma.com/make/

Figma Make 支持：

1
Prompt
2
↓
3
生成页面 / Prototype
4
↓
5
视觉编辑
6
↓
7
继续 Prompt
8
↓
9
代码

它特别适合：

你不知道自己要什么，但是看到图后知道“这个喜欢 / 这个不喜欢”。

10.1 实际模拟#

输入：

1
Create three substantially different design directions
2
for a developer-focused personal knowledge base.
3

4
The site contains:
5
- technical articles
6
- category navigation
7
- global search
8
- table of contents
9
- code blocks
10
- dark mode
11

12
Direction A:
13
technical product UI
14

15
Direction B:
16
warm editorial journal
17

18
Direction C:
19
minimal documentation
20

21
Do not just change colors.
22
Change typography, density, navigation,
23
surface treatment and content composition.
24

25
Avoid generic AI SaaS styling.

展开收起

生成之后：

1
我喜欢 B。
2

3
但是：
4
- Sidebar 使用 A
5
- Code block 使用 C
6
- 保留 B 的文章 Typography
7
- 降低装饰性
8
- 提高文章列表信息密度
9

10
Create a unified version.

10.2 最终怎么交给 Coding Agent#

你可以：

1
Figma Make
2
↓
3
截图 / Frame / Design Context
4
↓
5
Claude Code / Codex

给 Coding Agent：

1
这里是已经确认的 UI 设计。
2

3
不要重新进行视觉设计。
4

5
请分析：
6
- Layout
7
- Font hierarchy
8
- Spacing
9
- Color
10
- Radius
11
- Border
12
- Component structure
13

14
先整理 DESIGN.md，
15
再进行实现。

展开收起

11. v0：截图/参考图到高质量前端#

官网：

https://v0.app/

Screenshot 文档：

https://v0.app/docs/screenshots

Design Mode：

https://v0.app/docs/design-mode

11.1 最适合什么场景#

当你已经：

看到一个页面 / 截图，觉得它很好看。

但你不会描述它为什么好看。

直接把截图给 v0。

v0 可以分析：

layout
color
component hierarchy
likely interactions

11.2 实际模拟#

上传截图，然后：

1
不要复制截图中的：
2
- 品牌
3
- Logo
4
- 文案
5
- 图片素材
6
- 业务内容
7

8
只分析它的设计语言：
9

10
- overall composition
11
- typography hierarchy
12
- spacing rhythm
13
- navigation
14
- surface treatment
15
- border
16
- shadow
17
- radius
18
- information density
19
- responsive behavior
20

21
基于这些规律，
22
重新设计一个个人技术知识库首页。
23

24
技术栈：
25
Next.js + Tailwind + shadcn/ui。

展开收起

11.3 Design Mode 怎么用#

假设生成后的 Hero：

字太大。

不需要重新 Prompt 整页。

进入 Design Mode：

1
选中 Hero Title
2
→ 调 Font size
3
→ Line height
4
→ Width
5
→ Margin

再对选中区域：

1
Make this section quieter.
2
Reduce visual dominance without making it generic.

最后 Apply。

12. Landbook：找网站整体视觉方向#

官网：

https://land-book.com/

Landbook 更偏：

网站 / Landing Page / Portfolio / Marketing Site 的整体视觉灵感。

可以按：

Industry
Style
Type
Typography
Color

过滤。

12.1 实际模拟：完全没方向#

做一个 Developer Tool 官网。

先筛：

1
Industry:
2
Tech
3

4
Type:
5
SaaS / Software
6

7
Style:
8
Dark Colors
9
Visible Borders
10
Big Type
11

12
Typography:
13
Sans Serif

然后不要一次存 30 个。

只保留：

1
参考 1：喜欢 Hero
2
参考 2：喜欢 Typography
3
参考 3：喜欢 Navigation
4
参考 4：喜欢 Footer

交给 AI：

1
下面有 4 个视觉参考截图。
2

3
不要复制页面。
4

5
分别分析：
6
- 参考 1 的 Hero 为什么有效
7
- 参考 2 的 Typography hierarchy
8
- 参考 3 的 Navigation
9
- 参考 4 的 Footer composition
10

11
然后把这些规律组合成一个一致的 Design System。
12

13
不允许出现“拼凑感”。

12.2 不适合 Landbook 的场景#

如果你要研究：

1
Settings
2
Checkout
3
Onboarding
4
Complex dashboard
5
Search interaction

Mobbin / Refero 更适合。

13. Mobbin：找真实产品页面和完整用户流程#

官网：

https://mobbin.com/

Mobbin 的重点不是“漂亮 Landing Page”，而是：

真实 App / Web 产品实际怎么做。

适合：

1
Login
2
Onboarding
3
Settings
4
Checkout
5
Subscription
6
Home
7
Account
8
Search
9
Empty State

13.1 实际模拟：设计 Settings#

假设你要设计：

AI Coding Tool 的 Settings。

不要直接让 AI 写。

先在 Mobbin 找：

1
Settings
2
Preferences
3
Account
4
Appearance
5
Integrations

选 5~10 个真实产品。

然后对 Agent：

1
这些截图来自不同真实产品的 Settings 页面。
2

3
请做 UX pattern analysis。
4

5
不要评价哪个最好。
6

7
统计和总结：
8
- Sidebar / Tabs 使用方式
9
- Section grouping
10
- Label + description 结构
11
- Toggle placement
12
- Dangerous actions
13
- Save behavior
14
- Mobile behavior
15

16
最后设计适合当前产品的 Settings 信息架构。
17

18
暂时不要处理视觉风格。

展开收起

然后再结合 DESIGN.md 处理视觉。

这会把两个问题拆开：

1
Mobbin / Refero
2
→ UX Structure
3

4
DESIGN.md
5
→ Visual Style

14. Aceternity UI：找高视觉表现力组件#

官网：

https://ui.aceternity.com/

它提供很多：

Hero
Background
Animation
Cards
Spotlight
Grid
Text Effect
Shader

目前也提供面向 AI Agent 的使用方式 / MCP。

14.1 适合什么#

尤其适合：

1
Landing Page
2
Portfolio
3
Marketing
4
产品首页视觉焦点
5
特殊 Hero
6
背景效果
7
微交互

14.2 实际模拟#

假设：

当前首页太平淡。

不要直接要求：

1
加点酷炫动画。

而是：

1
从 Aceternity UI 中寻找适合当前首页 Hero 的视觉增强方案。
2

3
约束：
4
- 只允许一个主要视觉效果
5
- 不要 Gradient Blob
6
- 不要大量发光
7
- 不影响文字阅读
8
- prefers-reduced-motion 下必须安全降级
9
- Mobile 降低动效
10
- 必须符合 DESIGN.md
11

12
先给 3 个候选。
13
不要安装。

选中之后：

1
使用候选 2。
2

3
只借用交互机制，
4
重新适配：
5
- 当前项目 Colors
6
- Typography
7
- Radius
8
- Motion duration
9

10
不要让页面变成 Aceternity Demo。

14.3 重点#

Aceternity 应该是：

调味品。

不是：

全站每个 Section 都套动画。

15. shadcn/ui Blocks：找稳健、可维护的产品型页面骨架#

官网：

https://ui.shadcn.com/blocks

shadcn Blocks 更适合：

Dashboard
Login
Signup
Sidebar
Data Table
产品后台页面

例如官方 Dashboard Block 可以直接：

Terminal window

1
npx shadcn add dashboard-01

15.1 实际模拟#

需求：

快速做一个后台。

正确：

1
先从 shadcn Blocks 中寻找一个结构最接近当前需求的 Dashboard。
2

3
不要把它当最终设计。
4

5
它只负责：
6
- layout skeleton
7
- responsive behavior
8
- component structure
9

10
安装后再根据 DESIGN.md 修改：
11
- color
12
- typography
13
- density
14
- border
15
- radius
16
- navigation
17
- charts

展开收起

15.2 最佳定位#

1
shadcn
2
= 稳定产品骨架
3

4
DESIGN.md
5
= 设计语言
6

7
21st / Aceternity
8
= 个别高级组件
9

10
frontend-design
11
= 视觉实现
12

13
Impeccable
14
= 最后审查

这是比“所有东西都从零写”更稳的组合。

16. 浏览器视觉验收：Playwright / Chrome DevTools MCP#

这是整个 AI UI 工作流里非常容易被忽略的一步。

AI 修改代码 ≠ 页面真的好看。

必须：

1
Build
2
↓
3
启动
4
↓
5
打开真实浏览器
6
↓
7
Desktop 截图
8
↓
9
Mobile 截图
10
↓
11
分析
12
↓
13
一次集中修复

16.1 实际 Prompt#

1
页面实现完成后不要直接结束。
2

3
使用浏览器实际打开页面。
4

5
检查以下 viewport：
6

7
Desktop:
8
1440 x 900
9

10
Laptop:
11
1280 x 800
12

13
Mobile:
14
390 x 844
15

16
分别截图。
17

18
从截图而不是源码推测视觉问题。
19

20
检查：
21
- hierarchy
22
- alignment
23
- spacing
24
- text wrapping
25
- overflow
26
- content width
27
- navigation
28
- empty space
29
- card density
30
- mobile stacking
31
- button sizes
32
- code block overflow
33

34
把发现的问题一次汇总。
35

36
然后集中修复一轮。
37

38
修复后最多再进行一次确认截图，
39
不要陷入无限视觉微调。

展开收起

这和 Impeccable 当前强调的“bounded visual iteration”思路是相符的：

完整实现 → 一轮批量检查 → 集中修复 → 最多再确认一轮。

17. 从零开始的完整实战模拟#

下面模拟一个真实项目：

“我要做一个个人技术知识库，但没有任何 UI 方向。”

Phase 1：Agent 理解产品#

给 Claude Code / Codex：

1
当前任务是设计本项目 UI。
2

3
现在不要写代码。
4

5
先完整分析项目：
6

7
1. 产品是什么
8
2. 谁会使用
9
3. 最主要的 5 个用户任务
10
4. 页面类型
11
5. 内容密度
12
6. 当前技术栈
13
7. 已有组件
14
8. 已有 CSS / Theme
15
9. 是否已经存在 DESIGN.md
16
10. 是否有不能破坏的已有 UI
17

18
输出 UI Design Brief。

展开收起

预期得到：

1
产品：
2
个人技术知识库
3

4
主要任务：
5
- 找文章
6
- 浏览分类
7
- 阅读技术文章
8
- 复制代码
9
- 页面间跳转
10

11
核心：
12
阅读体验 > 营销视觉

Phase 2：Refero / Mobbin 研究#

1
使用 Refero 搜索：
2

3
developer documentation
4
knowledge base
5
technical editorial
6
content-heavy docs
7

8
至少分析 10 个相关真实页面。
9

10
重点研究：
11
- Navigation
12
- Search
13
- Article
14
- TOC
15
- Code block
16
- Mobile docs
17

18
不要开始 Build。

展开收起

Phase 3：Refero Styles 找视觉方向#

自己搜索：

1
documentation
2
developer tools
3
editorial
4
warm editorial
5
technical journal
6
minimal technical

保存 3~5 个喜欢的 Style / DESIGN.md。

Phase 4：生成三个方向#

1
结合：
2
- 当前项目需求
3
- Refero Research
4
- Refero Styles
5
- PRODUCT.md
6

7
提出 3 个明显不同的视觉方向。
8

9
A：
10
Developer Tool
11

12
B：
13
Warm Technical Editorial
14

15
C：
16
Minimal Documentation
17

18
不能只是换颜色。
19

20
分别定义：
21
Typography
22
Color
23
Layout
24
Navigation
25
Surface
26
Density
27
Radius
28
Border
29
Shadow
30
Motion
31
Article
32
Code Block
33
Mobile

展开收起

Phase 5：人工只做一个决定#

你只需要：

1
选 B。
2

3
但是导航采用 A，
4
代码块采用 C。

Phase 6：形成 DESIGN.md#

1
现在将已确认设计整理为项目根目录 DESIGN.md。
2

3
这份文件是未来所有页面的视觉 Source of Truth。
4

5
需要定义：
6
Overview
7
Colors
8
Typography
9
Layout
10
Elevation & Depth
11
Shapes
12
Components
13
Do's and Don'ts
14
Responsive
15
Motion
16
Accessibility
17

18
不要包含单个页面的临时决定。

展开收起

Phase 7：实现一个代表页面#

选择：

Article Detail。

因为它是知识库的核心页面。

1
读取 DESIGN.md。
2

3
使用 frontend-design skill。
4

5
只实现 Article Detail。
6

7
需要包含：
8
- Sidebar
9
- Breadcrumb
10
- Article header
11
- Article content
12
- Code block
13
- TOC
14
- Previous / Next
15
- Mobile layout
16

17
不要同时修改其他页面。

展开收起

Phase 8：真实浏览器验收#

1
启动项目。
2

3
实际打开 Article Detail。
4

5
检查：
6
1440x900
7
1280x800
8
390x844
9

10
截图并做视觉检查。
11

12
不要根据代码判断 UI。

Phase 9：Impeccable#

1
/impeccable critique article

修复。

然后：

1
/impeccable audit article

修复。

最后：

1
/impeccable polish article

Phase 10：推广全站#

当 Article Detail 已确认后：

1
当前 Article Detail 已作为 Design Reference。
2

3
接下来扩展到：
4
- 首页
5
- 分类
6
- 搜索
7
- About
8

9
必须继续遵循 DESIGN.md。
10

11
新页面允许解决新的 UX 问题，
12
但不得自行创造新的视觉语言。
13

14
如果 DESIGN.md 不足：
15
先提出 DESIGN.md 补充建议，
16
不要静默新增风格。

展开收起

18. 适合 Claude Code / Codex 的总 Prompt#

可以保存成自己的 Skill / Prompt。

1
你现在担任本项目的 Product Designer、
2
UI/UX Designer 和 Frontend Design Engineer。
3

4
当前项目可能没有明确视觉方向。
5

6
重要规则：
7

8
不要因为用户说“做一个页面”就立即开始写代码。
9

10
第一阶段永远先判断：
11
1. 是否已经存在 DESIGN.md
12
2. 是否存在成熟 UI
13
3. 是否已经有明确参考
14
4. 是否需要 Design Discovery
15

16
如果没有设计方向：
17

18
先理解：
19
- 产品是什么
20
- 核心用户
21
- 用户主要任务
22
- 页面类型
23
- 信息密度
24
- 技术栈
25
- 已有组件
26

27
然后进行设计研究。
28

29
如果可用，优先使用：
30
- Refero / Refero MCP
31
- Refero Styles
32
- Mobbin
33
- Landbook
34
- 21st
35
- UI/UX Pro Max
36

37
不要只根据模型记忆凭空设计。
38

39
至少提出 3 个明显不同的设计方向。
40

41
三个方向不能只是颜色不同。
42

43
需要在：
44
- Typography
45
- Color
46
- Layout
47
- Navigation
48
- Density
49
- Spacing
50
- Surface
51
- Radius
52
- Border
53
- Shadow
54
- Motion
55
- Content hierarchy
56

57
方面具有实际区别。
58

59
禁止默认 AI UI：
60

61
- purple/blue gradient
62
- glassmorphism
63
- every section in a card
64
- cards nested in cards
65
- oversized radius
66
- decorative badges everywhere
67
- meaningless glow
68
- giant generic hero
69
- excessive floating elements
70
- meaningless animation
71

72
选择方向以后，
73
形成 DESIGN.md。
74

75
DESIGN.md 是视觉 Source of Truth。
76

77
之后只实现一个最具有代表性的页面。
78

79
实现完成必须：
80
- 运行应用
81
- 打开真实浏览器
82
- 检查 Desktop
83
- 检查 Mobile
84
- 截图
85
- 进行 visual critique
86

87
如果 Impeccable 可用：
88
执行 critique → audit → polish。
89

90
最多进行两轮截图验证，
91
不要无限视觉循环。
92

93
只有代表页面确认后，
94
才将同一设计系统扩展到其他页面。
95

96
核心优先级：
97

98
1. Usability
99
2. Information hierarchy
100
3. Consistency
101
4. Readability
102
5. Visual identity
103
6. Decoration
104

105
真实产品参考优先于模型凭空想象。
106
明确设计方向优先于“现代、漂亮、高级”这类模糊形容词。

展开收起

19. 我的推荐组合#

如果不想把所有工具都装一遍，可以分三个级别。

19.1 最小方案#

1
Refero Styles
2
+
3
Anthropic frontend-design
4
+
5
DESIGN.md
6
+
7
浏览器截图验收

适合：

不想增加很多 MCP / Skill，只想明显改善 AI UI。

19.2 推荐方案#

1
Refero Styles
2
+
3
Refero MCP
4
+
5
Anthropic frontend-design
6
+
7
Impeccable
8
+
9
21st.dev
10
+
11
DESIGN.md
12
+
13
Browser visual review

这是最适合 Claude Code / Codex 日常开发的一套。

职责：

1
Refero
2
→ 找真实参考
3

4
DESIGN.md
5
→ 固化规则
6

7
frontend-design
8
→ 实现设计
9

10
21st
11
→ 找成熟组件
12

13
Impeccable
14
→ 审查和打磨
15

16
Browser
17
→ 真实视觉反馈

展开收起

19.3 完全没有任何设计方向的新项目#

建议：

1
Google Stitch
2
↓
3
探索 3~5 个方向
4
↓
5
选一个
6
↓
7
DESIGN.md
8
↓
9
Refero 验证真实产品模式
10
↓
11
Claude Code / Codex
12
↓
13
frontend-design
14
↓
15
21st / shadcn
16
↓
17
Impeccable

展开收起

这时 Stitch 的价值最大。

20. 参考链接#

Google Stitch#

Refero#

Refero Skill：

Terminal window

1
npx skills add https://github.com/referodesign/refero_skill

Anthropic frontend-design#

Impeccable#

安装：

Terminal window

1
npx impeccable install

21st.dev#

示例：

Terminal window

1
21st search "pricing table"
2
21st generate "a pricing table" --variants 3

UI/UX Pro Max#

Claude：

Terminal window

1
npx ui-ux-pro-max-cli init --ai claude

Codex：

Terminal window

1
npx ui-ux-pro-max-cli init --ai codex

Figma Make#

v0#

灵感 / 组件#

Landbook：

https://land-book.com/

Mobbin：

https://mobbin.com/

Aceternity UI：

https://ui.aceternity.com/

shadcn Blocks：

https://ui.shadcn.com/blocks

一句话总结#

以后遇到：

“我要做前端，但是我完全没有设计方向。”

不要直接进入代码阶段。

把默认流程改成：

1
Understand Product
2
→ Research Real Interfaces
3
→ Explore 3 Directions
4
→ Choose
5
→ DESIGN.md
6
→ Build One Representative Page
7
→ Browser Screenshot
8
→ Critique
9
→ Audit
10
→ Polish
11
→ Scale to the Rest of the Product

真正决定 AI UI 质量的，不是某一个“神级 Prompt”。

而是：

不要让模型凭空猜审美，要让它先看到真实设计、形成明确规则，再写代码。

Codex Microsoft Store 更新卡住排查

Wed, 23 Sep 2026 00:00:00 GMT

Codex Microsoft Store 更新卡住排查#

本文记录一台 Windows 10 电脑在 2026-09-21 至 2026-09-23 的实际案例。故障先后由两个不同问题造成，不能合并成一次“商店更新失败”。
2026-09-23 复核时，OpenAI.Codex 已安装目标版本 26.917.6896.0，包状态为 Ok。

1. 现象#

Codex 左下角持续显示更新图标。点击下载后，界面停在“正在安装更新／正在准备”；但“帮助 → 检查更新”却提示没有更新。Microsoft Store 中对应的 ChatGPT 项目显示排队或 0%。

这里容易看错对象：商店里的 ChatGPT 项目，在这台电脑上对应程序包 OpenAI.Codex。

2. 两个阻塞点#

阶段	本机证据	结论
下载服务无法启动（9 月 21—22 日）	Codex、Microsoft Store、HP Smart、应用安装程序出现 `0x80246008`；DoSvc 启动后立即停止，退出码为 `2`；系统事件 7023 报“系统找不到指定的文件”	空的 `Parameters` 子键遮住了上一级有效的 `ServiceDll`。移除该空子键后，服务可以启动。
商店队列停滞（9 月 23 日）	Codex 与商店购买组件均为 `Pending`、0 字节；此时 DoSvc 已正常运行	重启 `InstallService` 后队列开始推进。这只证明重启对这次队列有效，不能说明此前停滞的底层原因。

第一阶段修复后，一次仅下载测试曾出现 0x80072EE2 网络超时和 0 字节进度。随后同一测试文件下载完成，多个商店应用也更新成功，因此不能根据早期超时认定网络持续故障。

3. 修复 DoSvc#

HKLM\SYSTEM\CurrentControlSet\Services\DoSvc 根键中的 ServiceDll 是：

1
REG_EXPAND_SZ  %SystemRoot%\system32\dosvc.dll

文件存在且签名有效，但这台电脑上同级的 Parameters 子键存在且完全为空。静态检查 svchost.exe 的读取顺序可见：它先从 Parameters 读取 ServiceDll，只有子键不存在时才回退到服务根键。读取空子键返回错误 2，与 DoSvc 的启动失败一致。

2026-09-22 11<27> 做了最小修复：

备份 DoSvc 注册表子树、空子键权限和服务状态。
确认该子键没有值、没有下级键。
只删除这个空子键。
对比修复前后的注册表导出，确认差异只有该空子键。

没有修改上一级 ServiceDll，也没有清理商店缓存或应用数据。

随后 DoSvc 两次启动都进入 RUNNING，退出码为 0，不再出现错误 2。Microsoft Store、应用安装程序、HP Smart 和 Codex 的已安装版本也都发生了升级。

这个修复有明确前提：Parameters 必须完全为空，根键配置必须有效，并且先完成备份。它不是通用的注册表清理方法。

4. 推进停滞的商店队列#

到 2026-09-23，Codex 已安装 26.915.4065.0，商店日志指向待更新版本 26.917.6896.0，但 Codex 和 Microsoft.StorePurchaseApp 的实时队列仍是 Pending、0 字节。

应用更新器日志已经记录商店发现了更新，而应用内的“检查更新”仍提示没有更新。界面文字不能代替包版本和队列状态。商店日志里还出现过一次“RPC 服务器不可用”，它与队列停滞是否有因果关系并未确认。

11<02> 确认队列中没有正在安装的项目后，正常停止并重新启动 InstallService，没有强制结束进程。两个项目随后从 Pending 转为活动状态：

商店购买组件下载约 12.2 MB 后安装完成，版本由 22607.1401.4.0 升至 22608.1401.1.0。
Codex 先显示 ReadyToDownload，随后进入下载。

当天 11<10> 的中间状态是：两个服务均为 RUNNING、退出码 0；Codex 已下载 29,193,019 字节，进度 4%，已安装版本仍是旧版本。当时只能确认下载已开始。

2026-09-23 再次复核时，OpenAI.Codex 的已安装版本已经是 26.917.6896.0，包状态为 Ok。本次没有清空商店缓存、重装 Codex 或修改网络配置。

5. 后续判断#

Pending、ReadyToDownload、Downloading、Installing 是不同阶段。“正在安装更新”不足以证明已经进入安装。
重启 InstallService 只说明它解决了这一次队列停滞，不能推广为所有商店更新故障的修复方法。
如果下载再次停滞，应按新的时间戳检查队列、已下载字节和事件，不要沿用上一次的错误码。
商店更新仍不可用时，可改用Codex Windows 微软商店安装包提取与手动更新。

Codex 与 Claude Code 规则文件统一

Wed, 23 Sep 2026 00:00:00 GMT

Codex 与 Claude Code 规则文件统一#

适用场景：同一台电脑同时使用 Codex 和 Claude Code，希望个人规则和项目规则都只维护一份。

全局规则只写 ~/.codex/AGENTS.md

Claude Code 通过 @ 引用这份规则

新项目只写 AGENTS.md

只有 CLAUDE.md 的旧项目由 Codex fallback 兼容

1. 最终结构#

1
全局：
2
~/.codex/AGENTS.md      ← 唯一维护的个人规则
3
~/.claude/CLAUDE.md     ← 只写 @~/.codex/AGENTS.md
4

5
项目：
6
project/AGENTS.md       ← 唯一维护的项目规则
7
project/CLAUDE.md       ← 可选；需要时只写 @AGENTS.md

Windows 上的用户目录对应：

1
C:\Users\<用户名>\.codex\AGENTS.md
2
C:\Users\<用户名>\.claude\CLAUDE.md

不使用软链接，也不再增加第三份公共规则文件。

2. 全局规则#

~/.codex/AGENTS.md 保存真正的个人规则，例如：

1
# Global Instructions
2

3
- 未经用户明确授权禁止 git push。
4
- 修改代码时优先最小改动。
5
- 不做与当前任务无关的重构。
6
- 修改完成后执行必要验证。
7
- Git 操作前注意敏感信息。

~/.claude/CLAUDE.md 只保留：

1
@~/.codex/AGENTS.md

Claude Code 会在载入用户级 CLAUDE.md 时导入这份文件。用户级 ~/.claude/CLAUDE.md 不算项目规则，因此不会阻止项目中的 AGENTS.md 被读取。

1
~/.codex/AGENTS.md
2
        ├─→ Codex
3
        └─→ ~/.claude/CLAUDE.md ─→ Claude Code

3. 新项目#

新项目只保留：

1
project/
2
└─ AGENTS.md

Codex 会直接读取它。Claude Code 在默认模式下发现项目没有 CLAUDE.md，也会读取 AGENTS.md。这是维护成本最低的形式。

4. 兼容旧项目#

旧项目可能只有：

1
project/
2
└─ CLAUDE.md

Codex 默认不读取它。在 ~/.codex/config.toml 的顶层增加：

1
project_doc_fallback_filenames = ["CLAUDE.md"]

它必须是顶层字段，不能写进某个 [section] 下面。

fallback 的含义是“没有标准规则文件时才读取”，不是两份一起读取：

1
AGENTS.override.md 存在 → 使用它
2
否则 AGENTS.md 存在     → 使用它
3
否则 CLAUDE.md 存在     → 使用它

因此，项目里已经有 AGENTS.md 时，Codex 不会再加载同目录的 CLAUDE.md。

5. 两边都有文件时#

如果项目同时保留两份文件，默认读取结果会不同：

项目文件	Codex（已配置 fallback）	Claude Code 默认模式
只有 `AGENTS.md`	`AGENTS.md`	`AGENTS.md`
只有 `CLAUDE.md`	`CLAUDE.md`	`CLAUDE.md`
两份都有	只用 `AGENTS.md`	只用 `CLAUDE.md`

要消除最后一行的差异，让 CLAUDE.md 只负责导入：

1
@AGENTS.md

Claude Code 仍从 CLAUDE.md 进入，但实际规则来自 AGENTS.md；Codex 则直接读取 AGENTS.md。不要把 @ 写进 AGENTS.md，Codex 不会处理这种导入。

如果确实需要 Claude Code 同时主动加载两份独立内容，可以在 /config 的 Project instructions 中改为 claude-md-and-agents-md。同一份由 @AGENTS.md 导入的内容会去重。没有这种需求时，保持默认的 claude-md-or-agents-md 即可。

6. 多层目录#

Codex 会从全局目录一直读到当前工作目录，更靠近当前目录的规则更具体：

1
~/.codex/AGENTS.md
2
        ↓
3
project/AGENTS.md
4
        ↓
5
project/module-a/AGENTS.md

根目录写通用规则，模块目录只写该模块的特殊规则，不要把根规则整份复制到子目录。

7. 迁移顺序#

全局只维护 ~/.codex/AGENTS.md，让 ~/.claude/CLAUDE.md 引用它。
给 Codex 配置 CLAUDE.md fallback，先兼容旧项目。
新项目只创建 AGENTS.md。
整理旧项目时，把规则移入 AGENTS.md，原 CLAUDE.md 改为 @AGENTS.md。
确认所用 Claude Code 能直接读取 AGENTS.md 后，再考虑删除仅作兼容的 CLAUDE.md。

修改配置后重新打开会话。Claude Code 可用 /context 查看实际载入的规则文件，并用 /config 确认 Project instructions 的模式。Codex 可以在临时项目中分别放入内容明显不同的 AGENTS.md 和 CLAUDE.md，用新会话确认实际读取了哪一份。

参考#

Git 与 GitHub SSH 代理配置教程

Sun, 20 Sep 2026 00:00:00 GMT

适用场景：Windows + Git for Windows + 本地代理工具（Clash / FlClash 等）。

Git 的 HTTP/HTTPS 仓库走本地代理端口

Git 的 SSH 仓库通过 ~/.ssh/config 走同一个本地代理端口

GitHub、GitLab 均可使用

本文用 <本地代理端口> 作为示例占位符，请替换成你实际代理工具监听的端口。

1. 先理解两套代理分别管什么#

Git 仓库常见有两种地址。

HTTPS 地址#

1
https://github.com/user/repo.git
2
https://gitlab.com/user/repo.git

这种连接受 Git 的：

1
http.proxy
2
https.proxy

控制。

SSH 地址#

1
git@github.com:user/repo.git
2
git@gitlab.com:user/repo.git

这种连接实际上由 ssh.exe 建立，不会读取 Git 的 http.proxy / https.proxy。

因此最终方案是：

1
Git HTTPS
2
    ↓
3
~/.gitconfig
4
    ↓
5
127.0.0.1:<本地代理端口>
6

7
Git SSH
8
    ↓
9
~/.ssh/config
10
    ↓
11
ProxyCommand
12
    ↓
13
127.0.0.1:<本地代理端口>

2. 查看当前 Git 代理配置#

推荐先执行：

Terminal window

1
git config --show-origin --show-scope --get-regexp "proxy"

它会显示：

配置作用域
配置文件位置
当前代理内容

也可以只查看全局配置：

Terminal window

1
git config --global --get-regexp proxy

例如可能看到：

1
http.https://github.com.proxy http://127.0.0.1:<本地代理端口>
2
https.https://github.com.proxy http://127.0.0.1:<本地代理端口>

这代表之前配置的是“仅 GitHub 使用代理”。

3. 两种 Git 代理策略怎么选#

Git 的 HTTP/HTTPS 代理有两种配法，适用场景相反：

策略	配置	适合
全局代理	通用 `http.proxy` / `https.proxy`	所有 Git 远程都需要走代理，没有必须直连的仓库
URL 级代理	`http.https://github.com/.proxy`	只有 GitHub 走代理，GitLab 或公司仓库必须直连

如果公司仓库、内网 GitLab 必须直连，用 URL 级配置，只给 GitHub 配代理：

Terminal window

1
git config --global http.https://github.com/.proxy http://127.0.0.1:<本地代理端口>

这种配法的详细说明见 Codex Claude 软件级代理设置教程的「方案三」，本文不重复。

下面以「所有 Git 仓库统一走代理」为例。如果你已经在用 URL 级配置，可以跳到第 7 节配置 SSH。

4. 清理旧的 GitHub 专用代理#

如果准备恢复为“所有 HTTPS Git 仓库统一走代理”，先删除旧的 GitHub 专用配置：

Terminal window

1
git config --global --unset-all http.https://github.com.proxy
2
git config --global --unset-all https.https://github.com.proxy

如果某条配置不存在，Git 可能返回非 0 状态，不影响后续配置。

再次检查：

Terminal window

1
git config --global --get-regexp proxy

5. 配置所有 Git HTTP/HTTPS 请求走代理#

执行：

Terminal window

1
git config --global http.proxy http://127.0.0.1:<本地代理端口>
2
git config --global https.proxy http://127.0.0.1:<本地代理端口>

检查：

Terminal window

1
git config --global --get-regexp proxy

正常应看到：

1
http.proxy http://127.0.0.1:<本地代理端口>
2
https.proxy http://127.0.0.1:<本地代理端口>

Windows 下，全局 Git 配置通常位于：

1
C:\Users\你的用户名\.gitconfig

也可以直接打开：

Terminal window

1
git config --global --edit

对应配置大致为：

1
[http]
2
    proxy = http://127.0.0.1:<本地代理端口>
3

4
[https]
5
    proxy = http://127.0.0.1:<本地代理端口>

6. 判断当前仓库使用 HTTPS 还是 SSH#

进入 Git 仓库后执行：

Terminal window

1
git remote -v

如果看到：

1
origin  https://github.com/user/repo.git

说明当前仓库使用 HTTPS，会读取 Git 全局代理。

如果看到：

1
origin  git@github.com:user/repo.git

说明当前仓库使用 SSH，需要继续配置 ~/.ssh/config。

7. 配置 SSH Git 走代理#

7.1 Windows 下 SSH 配置文件位置#

默认位置：

1
C:\Users\你的用户名\.ssh\config

也就是：

1
~/.ssh/config

注意：

1
config

没有文件后缀。

如果文件不存在，可以手动创建。

7.2 先确认 connect.exe 是否存在#

在 PowerShell 执行：

Terminal window

1
where.exe connect

Git for Windows 常见位置可能是：

1
C:\Program Files\Git\mingw64\bin\connect.exe

或类似路径。

只要：

Terminal window

1
where.exe connect

能找到 connect.exe，下面的 ProxyCommand 一般即可直接使用。

7.3 给 GitHub 配置 SSH 代理#

编辑：

1
C:\Users\你的用户名\.ssh\config

添加：

1
Host github.com
2
    HostName github.com
3
    User git
4
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

其中：

1
-S 127.0.0.1:<本地代理端口>

表示通过本地 SOCKS 代理连接目标服务器。

如果本地代理端口是代理工具的 Mixed Port，一般同时支持 HTTP 和 SOCKS，可直接使用。

7.4 给 GitLab 配置 SSH 代理#

继续添加：

1
Host gitlab.com
2
    HostName gitlab.com
3
    User git
4
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

最终可以写成：

1
Host github.com
2
    HostName github.com
3
    User git
4
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p
5

6
Host gitlab.com
7
    HostName gitlab.com
8
    User git
9
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

8. 如果已经配置 SSH Key#

如果你原本的 SSH 配置已经包含：

1
Host github.com
2
    HostName github.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_github

不要重新再写一个相同的 Host github.com，直接把代理配置追加进去即可：

1
Host github.com
2
    HostName github.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_github
5
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

GitLab 同理：

1
Host gitlab.com
2
    HostName gitlab.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_gitlab
5
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

9. 测试 GitHub SSH#

确保本地代理工具正在运行，并且本地代理端口正常监听。

执行：

Terminal window

1
ssh -T git@github.com

首次连接可能提示确认主机指纹：

1
Are you sure you want to continue connecting (yes/no/[fingerprint])?

确认域名无误后输入：

1
yes

认证正常时，通常会看到类似：

1
Hi xxx! You've successfully authenticated, but GitHub does not provide shell access.

这表示 SSH Key 和 SSH 代理均已经工作。

10. 测试 GitLab SSH#

执行：

Terminal window

1
ssh -T git@gitlab.com

正常情况下会出现 GitLab 的欢迎或认证成功信息。

11. 测试 Git HTTPS#

可以使用现有 HTTPS 仓库：

Terminal window

1
git fetch

或者：

Terminal window

1
git pull

只要仓库 Remote 是：

1
https://...

就会读取：

1
http.proxy
2
https.proxy

并通过：

1
127.0.0.1:<本地代理端口>

访问。

12. 查看本机代理端口是否正在监听#

PowerShell：

Terminal window

1
Get-NetTCPConnection -LocalPort <本地代理端口> -ErrorAction SilentlyContinue

也可以：

Terminal window

1
netstat -ano | findstr :<本地代理端口>

如果能看到监听状态，例如：

1
LISTENING

说明本地代理端口已经启动。

13. 查看 Git 实际使用哪个 ssh.exe#

Windows 上可能同时存在：

1
C:\Windows\System32\OpenSSH\ssh.exe

和：

1
C:\Program Files\Git\usr\bin\ssh.exe

查看：

Terminal window

1
where.exe ssh

还可以检查 Git 是否单独指定 SSH：

Terminal window

1
git config --show-origin --get core.sshCommand

以及环境变量：

Terminal window

1
$env:GIT_SSH
2
$env:GIT_SSH_COMMAND

如果这些都没有特殊设置，Git 一般按照当前环境找到可用的 ssh.exe。

14. 查看 SSH 最终展开后的配置#

OpenSSH 可以查看某个 Host 最终会使用哪些配置：

Terminal window

1
ssh -G github.com

可以重点寻找：

1
hostname
2
user
3
proxycommand
4
identityfile

例如：

Terminal window

1
ssh -G github.com | Select-String "hostname|user|proxycommand|identityfile"

如果配置生效，应能看到对应的：

1
proxycommand connect -S 127.0.0.1:<本地代理端口> ...

15. 最终推荐配置#

Git HTTPS#

全局：

Terminal window

1
git config --global http.proxy http://127.0.0.1:<本地代理端口>
2
git config --global https.proxy http://127.0.0.1:<本地代理端口>

对应：

1
C:\Users\你的用户名\.gitconfig

Git SSH#

1
C:\Users\你的用户名\.ssh\config

内容：

1
Host github.com
2
    HostName github.com
3
    User git
4
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p
5

6
Host gitlab.com
7
    HostName gitlab.com
8
    User git
9
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

如果已经配置 SSH Key，则将 ProxyCommand 加入原有对应 Host 块中。

16. 最终流量结构#

1
HTTPS GitHub / GitLab / 其他 Git
2
                │
3
                ▼
4
          Git .gitconfig
5
                │
6
                ▼
7
       http://127.0.0.1:<本地代理端口>
8
                │
9
                ▼
10
             本地代理工具
11

12

13
SSH GitHub / GitLab
14
                │
15
                ▼
16
           ssh.exe
17
                │
18
                ▼
19
          ~/.ssh/config
20
                │
21
                ▼
22
 ProxyCommand connect -S 127.0.0.1:<本地代理端口>
23
                │
24
                ▼
25
             本地代理工具

展开收起

这样 HTTP/HTTPS 和 SSH 两套 Git 连接都可以统一经过本地代理。

17. 撤销 Git HTTP/HTTPS 代理#

如果以后不想让 Git HTTP/HTTPS 走代理：

Terminal window

1
git config --global --unset-all http.proxy
2
git config --global --unset-all https.proxy

检查：

Terminal window

1
git config --global --get-regexp proxy

没有输出即代表 Git 全局代理已删除。

18. 撤销 SSH 代理#

打开：

1
C:\Users\你的用户名\.ssh\config

删除 GitHub / GitLab Host 块中的：

1
ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

例如从：

1
Host github.com
2
    HostName github.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_github
5
    ProxyCommand connect -S 127.0.0.1:<本地代理端口> %h %p

恢复为：

1
Host github.com
2
    HostName github.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_github

即可。

19. 常见问题#

问题 1：配置了 Git 全局 proxy，为什么 SSH 不走代理？#

因为：

1
http.proxy
2
https.proxy

属于 Git HTTP 传输层配置。

而：

1
git@github.com:...

调用的是 SSH，两者完全独立。

因此 SSH 必须通过：

1
~/.ssh/config

或其他 SSH/系统级代理方式单独处理。

问题 2：为什么推荐 `.ssh/config`，而不是 Proxifier 接管 ssh.exe？#

两种方案都可以。

使用 .ssh/config 的优点是：

配置属于 SSH 自身
哪些域名走代理一目了然
不依赖 Proxifier 的进程匹配
不影响其他使用 ssh.exe 的场景
SSH Key 和代理规则可以放在一起管理

如果 GitHub/GitLab 的 SSH 使用比较固定，.ssh/config 通常更加清晰。

问题 3：本地代理端口到底应该使用 HTTP 还是 SOCKS？#

Git HTTPS 使用：

1
http://127.0.0.1:<本地代理端口>

SSH ProxyCommand connect 使用：

1
-S 127.0.0.1:<本地代理端口>

后者表示 SOCKS。

如果本地代理端口是代理工具的 Mixed Port，一般可以同时支持这两种方式。

问题 4：公司 GitLab 不希望走代理怎么办？#

不要给公司 GitLab 的 Host 配：

1
ProxyCommand

例如：

1
Host gitlab.company.com
2
    HostName gitlab.company.com
3
    User git
4
    IdentityFile ~/.ssh/id_ed25519_company

即可继续直连。

需要注意：如果你同时设置了 Git 全局：

1
http.proxy
2
https.proxy

那么公司 Git 仓库如果使用 HTTPS Remote，仍会尝试走全局 Git HTTP 代理。

这种情况下可以再根据域名做例外配置，或者公司仓库统一使用 SSH。

20. 日常排查命令速查#

查看 Git 代理：

Terminal window

1
git config --show-origin --show-scope --get-regexp proxy

查看 Remote：

Terminal window

1
git remote -v

查看 SSH：

Terminal window

1
where.exe ssh

查看 connect：

Terminal window

1
where.exe connect

查看 GitHub SSH 展开配置：

Terminal window

1
ssh -G github.com

测试 GitHub：

Terminal window

1
ssh -T git@github.com

测试 GitLab：

Terminal window

1
ssh -T git@gitlab.com

检查代理端口：

Terminal window

1
netstat -ano | findstr :<本地代理端口>

配置总结#

最终只需要记住两处：

1
C:\Users\你的用户名\.gitconfig

负责：

1
Git HTTP / HTTPS

以及：

1
C:\Users\你的用户名\.ssh\config

负责：

1
Git SSH

统一指向：

1
127.0.0.1:<本地代理端口>

即可。

Windows 索引

Fri, 18 Sep 2026 00:00:00 GMT

Windows 索引#

Windows 软件、效率工具与环境配置笔记。

软件与效率#

电脑必备软件：常用工具清单
KeePass 密码管理：KeePass 安装、安全配置、自动输入与插件实践
KeePassXC 推荐配置与使用指南：KeePassXC 2.7.12 简体中文界面推荐配置、浏览器集成、TOTP/Passkey 与 SSH Agent

Codex#

Codex Windows 微软商店安装包提取与手动更新：Microsoft Store 安装包提取、更新与备份
Codex Microsoft Store 更新卡住排查：DoSvc 0x80246008 与商店队列停滞的一次实际排障
Codex Claude 软件级代理设置教程：Codex、Claude、Proxifier 的进程级代理与 DNS 排障
Codex 与 Claude Code 规则文件统一：用一份 AGENTS.md 同时维护 Codex 和 Claude Code 规则
Claude Code Hook 通知与提示音配置：权限确认、回答完成和错误结束时的 Windows 通知与提示音
ChatGPT Windows 升级后 Proxifier 网络异常排查：升级后启动、用量、侧边栏附件失败与 Proxifier DNS 链路排查
Tampermonkey 多电脑同步指南：多台电脑间同步用户脚本、备份与冲突处理

网络与代理#

为 Linux.do 指定固定 DNS 与直连规则：Clash Verge Rev、FlClash 的 DoH 与 DIRECT 规则
用一台美国 VPS 搭建 AI 专用出口：Xray REALITY + FlClash + Mihomo 动态 AI 分流：VPS 自建 Xray REALITY 与 AI 分流

Git 与 GitHub#

GitHub 提交邮箱隐私与 Git 多身份配置：隐藏提交邮箱，并按目录自动切换公司、个人身份

知识库发布#

Obsidian 私人知识库自动发布 Quartz 与 Cloudflare Pages：从私人笔记筛选公开内容，并自动部署为静态网站
Quartz 4 升级 Quartz 5 复盘：Quartz 大版本迁移过程、问题排查与主题调研

Windows 使用 KeePassXC 与 SSH Agent 管理 SSH 密钥

Thu, 17 Sep 2026 00:00:00 GMT

Windows 使用 KeePassXC 与 SSH Agent 管理 SSH 密钥#

本文在 Windows 10/11 上使用系统 OpenSSH Agent，并把私钥作为附件保存在 KeePassXC 数据库中。解锁数据库后，KeePassXC 将密钥加载到 Agent；SSH 客户端无需直接读取裸私钥文件。

Important

KeePassXC 不是 SSH Agent。它是 Windows OpenSSH Agent 或 Pageant 的客户端，负责在数据库解锁和锁定时添加、移除密钥。

最终结构#

1
KeePassXC 数据库
2
└─ SSH 条目
3
   ├─ 密码字段：私钥 passphrase
4
   └─ 附件：OpenSSH 私钥
5
          ↓ 数据库解锁时加载
6
Windows OpenSSH Authentication Agent
7
          ↓
8
ssh / Git
9
          ↓
10
服务器 ~/.ssh/authorized_keys 中的对应公钥

一、规划密钥#

推荐每台电脑使用独立密钥：

1
家用电脑  → Key A
2
工作电脑  → Key B
3
笔记本    → Key C

把各自的公钥添加到需要访问的服务器。某台设备丢失或停用时，只需删除对应公钥，不会影响其他设备。

多台电脑共用同一私钥虽然可行，但服务器无法区分设备，单机失陷后也不能只撤销这一台。KeePassXC 数据库可以同步，密钥身份仍应按设备拆分。

二、启用 Windows OpenSSH Agent#

普通 PowerShell 检查组件：

Terminal window

1
ssh -V
2
Get-Service ssh-agent

若找不到 ssh，在 Windows 的 设置 → 应用 → 可选功能 中安装 OpenSSH 客户端。

以管理员身份打开 PowerShell：

Terminal window

1
Get-Service ssh-agent | Set-Service -StartupType Automatic
2
Start-Service ssh-agent
3
Get-Service ssh-agent

随后检查：

Terminal window

1
ssh-add -l

出现 The agent has no identities. 表示 Agent 正常，只是尚未加载密钥。

三、生成 Ed25519 密钥#

Terminal window

1
ssh-keygen -t ed25519 -C "device-name"

默认会在当前用户的 .ssh 目录生成：

1
id_ed25519       私钥
2
id_ed25519.pub   公钥

为私钥设置强 passphrase。它用于解密私钥，与服务器账号密码完全不同。

Warning

服务器只接收公钥。私钥不可上传到服务器、公开仓库、聊天记录或普通云盘目录。

四、把私钥保存在 KeePassXC#

新建条目，例如：

1
标题：SSH Key - device-name
2
用户名：登录用户名或设备名
3
密码：私钥 passphrase
4
URL：ssh://server.example.com

若私钥没有 passphrase，密码字段保持为空；不要填写服务器密码。

编辑条目，进入 高级 → 附件 → 添加，选择没有 .pub 后缀的私钥文件。使用附件后，私钥会保存在加密的 KDBX 中；选择“外部文件”则只保存路径引用，换电脑后仍需单独复制文件。

检查文件类型：

Terminal window

1
Get-Content "$env:USERPROFILE\.ssh\id_ed25519" -TotalCount 1

OpenSSH 私钥开头应类似：

1
[OpenSSH 私钥头部标记]

若看到 ssh-ed25519 AAAA...，说明选中的是公钥。

五、配置 KeePassXC SSH Agent 集成#

进入 工具 → 设置 → SSH Agent：

1
☑ 启用 SSH Agent 集成
2
☑ OpenSSH for Windows

设置页应显示 Agent 连接正常。不要同时混用 Windows OpenSSH、Git for Windows 自带 Agent 和 Pageant。

再编辑 SSH 条目，进入 SSH Agent：

私钥来源选择刚添加的附件。
开启“数据库解锁时添加密钥”。
开启“数据库锁定时移除密钥”。

也可在条目右键菜单中手动把密钥添加到 SSH Agent。验证：

Terminal window

1
ssh-add -l

正常时会显示密钥指纹和类型，例如 ED25519。

六、把公钥安装到服务器#

读取公钥：

Terminal window

1
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub"

首次使用原有密码或云厂商控制台登录服务器，然后执行：

Terminal window

1
mkdir -p ~/.ssh
2
chmod 700 ~/.ssh
3
nano ~/.ssh/authorized_keys
4
chmod 600 ~/.ssh/authorized_keys

把完整公钥粘贴为一行。多台电脑的公钥各占一行：

1
ssh-ed25519 AAAA... home-pc
2
ssh-ed25519 BBBB... work-pc

Warning

保留当前已登录的 SSH 会话，在另一个终端确认密钥登录成功后再退出。不要在首次测试前关闭密码登录。

七、测试登录#

确认 Agent 已加载密钥：

Terminal window

1
ssh-add -l
2
ssh user@203.0.113.10 -p 2222

如需查看认证过程：

Terminal window

1
ssh -v user@203.0.113.10 -p 2222

成功时日志通常会包含：

1
Offering public key
2
Server accepts key
3
Authenticated ... using "publickey"

八、使用 SSH Config 简化命令#

编辑当前用户 .ssh\config：

1
Host server-a
2
    HostName 203.0.113.10
3
    User user
4
    Port 2222

之后只需：

Terminal window

1
ssh server-a

密钥较少时，OpenSSH 会从 Agent 中选择服务器接受的身份，无需设置 IdentityFile。

Agent 中密钥很多时#

若出现 Too many authentication failures，为每台服务器精确指定公钥并限制身份：

1
Host server-a
2
    HostName 203.0.113.10
3
    User user
4
    Port 2222
5
    IdentityFile ~/.ssh/server-a_ed25519.pub
6
    IdentitiesOnly yes

这里可以让 IdentityFile 指向对应公钥；私钥仍由 Agent 提供，不必以裸文件长期保存在 .ssh 目录。

九、常见故障#

`The agent has no identities.`#

依次检查：

ssh-agent 服务是否为 Running。
KeePassXC 是否启用了 OpenSSH for Windows 集成。
条目是否选择了正确的私钥附件。
数据库解锁时自动添加是否开启。
锁定再解锁数据库，或手动添加条目密钥。

KeePassXC 提示解密失败#

密码字段必须填写私钥 passphrase，而不是服务器密码。可以验证私钥：

Terminal window

1
ssh-keygen -y -f "$env:USERPROFILE\.ssh\id_ed25519"

输入正确 passphrase 后应输出对应公钥。

PowerShell 可用，Git Bash 不可用#

检查实际调用的 SSH：

Terminal window

1
where.exe ssh

优先统一使用：

1
C:\Windows\System32\OpenSSH\ssh.exe

Git for Windows 的 MSYS2 Agent socket 不受 KeePassXC 支持。安装 Git 时选择 Windows OpenSSH，或配置 Git 使用系统 OpenSSH。

同步盘保存 KDBX 失败#

若 OneDrive 等同步工具短暂占用文件：

不要立即关闭 KeePassXC。
等待同步完成后再次保存。
把 KDBX 设置为始终保留在本机。
检查窗口标题是否有 *，它表示仍有未保存修改。

同步不是备份。至少保留云端版本历史和一份独立离线备份。

十、安全收尾#

连续验证以下场景后，才考虑关闭服务器密码认证：

KeePassXC 重启后可以加载密钥。
数据库锁定后密钥从 Agent 移除，解锁后重新加入。
Windows 重启后 ssh-agent 自动运行。
新终端可以稳定完成公钥登录。
云厂商控制台或其他应急入口可用。

本地裸私钥确认已进入 KDBX 且有可靠备份后，可按自己的恢复策略安全删除；公钥和 SSH Config 可以保留。

验收清单#

Windows OpenSSH 客户端可用。
ssh-agent 自动启动且状态为 Running。
KeePassXC 已连接 OpenSSH for Windows。
私钥附件与 passphrase 配置正确。
ssh-add -l 能看到预期指纹。
服务器 authorized_keys 只包含需要保留的公钥。
ssh -v 确认使用 publickey 认证。
KDBX 有版本历史与独立备份。

参考资料#

CF-Server-Monitor 部署与运维指南

Thu, 17 Sep 2026 00:00:00 GMT

CF-Server-Monitor 部署与运维指南#

CF-Server-Monitor 把监控面板部署在 Cloudflare Workers 上，使用 D1 保存数据、Durable Objects 与 WebSocket 提供实时更新；每台被监控主机运行 cf-probe Agent，主动向 Worker 上报状态。

Important

项目仍在快速迭代。界面名称、Agent 参数和升级方式应以上游 README 与部署后的管理后台为准，不要照搬旧版本命令。

架构与适用场景#

1
VPS-A ─┐
2
VPS-B ─┼─ cf-probe ─ HTTPS / WSS ─> Cloudflare Worker
3
VPS-C ─┘                              ├─ D1：配置与历史数据
4
                                     ├─ Durable Objects：实时连接
5
                                     └─ 管理面板与状态页

它适合少量到中等规模的个人服务器监控：不需要额外维护主控 VPS，Agent 也无需开放 Web 管理端口。若需要完整的主机可观测性、日志分析或复杂告警，应再评估 Netdata、Prometheus、Beszel 或 Uptime Kuma 等方案。

部署前准备#

Cloudflare 账号。
GitHub 账号。
至少一台可通过 SSH 管理的 Linux 主机。
一段随机生成的 API_SECRET。

为减少 Shell 粘贴和转义问题，API_SECRET 可使用足够长的字母数字组合。不要在笔记、截图、终端历史或聊天记录中保存真实 Secret。

一、连接 GitHub 部署 Worker#

打开 CF-Server-Monitor 官方仓库，Fork 到自己的 GitHub 账号。
进入 Cloudflare Dashboard 的 Workers & Pages。
创建应用并连接 GitHub，选择刚 Fork 的仓库。

按上游 README 填写构建配置。当前常用值为：

1
Build command: npm run build:frontend
2
Deploy command: npx wrangler deploy

完成首次部署，确认构建日志成功。

使用 Fork 的好处是可以通过 GitHub 的 Sync fork 获取上游更新，并触发 Cloudflare 重新部署。

二、配置 Secret 与首次登录#

进入 Worker 的 Settings → Variables and Secrets，设置：

1
API_SECRET=<随机长字符串>

保存后确认新版本已部署到 Production。默认管理账号通常为 admin，初始密码使用 API_SECRET；首次登录后应立即设置独立的管理员密码。

1
API_SECRET     → 仅供 Agent 上报认证
2
管理员密码     → 仅供人登录后台

Warning

Agent 安装命令通常包含 API_SECRET、服务器 ID 和 Worker 地址。不要公开命令全文，也不要在截图中暴露浏览器请求头里的 Bearer Token。

管理后台通常位于：

1
https://<worker-name>.<account-subdomain>.workers.dev/admin

实际路径以上游当前版本为准。

三、添加服务器并安装 Agent#

在管理后台新增服务器，例如：

1
vps-us-01
2
vps-sg-01

新记录在 Agent 上线前显示离线是正常现象。点击服务器旁的复制按钮，使用后台生成的安装命令；它会携带正确的服务器 ID、Worker URL、Secret 和当前版本支持的参数。

Tip

不要从旧教程手工拼接完整安装命令。项目的 Agent、参数和安装脚本会随版本变化，后台生成的命令更可靠。

安装后检查服务：

Terminal window

1
systemctl status cf-probe --no-pager
2
journalctl -u cf-probe -n 100 --no-pager

若使用用户级 systemd：

Terminal window

1
systemctl --user status cf-probe --no-pager
2
journalctl --user -u cf-probe -n 100 --no-pager

后台出现 CPU、内存、磁盘、网络、延迟和最近上报时间，即说明链路已打通。

四、基础配置建议#

上报与采集间隔#

先使用项目默认值。个人少量主机通常不需要追求数秒级刷新；服务器增加后，可适当延长上报间隔以减少 Worker 请求、D1 写入和历史数据量。

流量重置日#

按服务商实际账单周期设置 reset_day。若套餐每月 15 日重置流量，就不要保留默认的 1 日，否则月流量统计会失真。

服务器命名#

使用不暴露内部信息的统一格式：

1
用途-地区-序号
2
web-us-01
3
relay-sg-01

公开状态页时隐藏 IP、内部备注、价格、到期时间以及不需要展示的主机。

域名#

workers.dev 可用于初期验证。需要自定义域名时，在 Worker 的 Domains & Routes 中添加 Custom Domain，再让 Agent 改用新地址。D1 数据、服务器 ID 和 Secret 无需因此重建。

五、安全加固#

管理员密码与 API_SECRET 分离。
Agent 优先以低权限用户运行；使用用户级 systemd 时按需启用 linger。
状态页默认保持私有，只公开必要字段。
第三方背景图、脚本、字体和 Webhook 只允许可信来源。
定期轮换已泄露或疑似泄露的 Secret，并重新生成 Agent 安装命令。
升级前导出服务器配置，并记录当前部署版本。

项目使用 CSP 限制外部资源。背景图、CSS、JS、字体或外部 API 加载失败时，应添加最小可信域名白名单，不要关闭或全面放开 CSP。

六、常见故障#

Shell 持续显示 `>`#

这通常表示引号未闭合或复制的命令被截断，并非安装程序卡死。

按 Ctrl + C 退出续行状态。
重新从后台复制完整命令。
检查 Secret 是否因特殊字符破坏 Shell 引号。

Agent 在线但后台仍显示离线#

依次检查：

cf-probe 服务和日志。
主机能否访问 Worker URL。
Worker URL、服务器 ID、API_SECRET 是否来自同一次后台生成。
Worker 最新部署是否已进入 Production。
修改 Secret 后是否重新安装或更新 Agent 配置。

修改 Secret 后仍出现旧值#

先确认 Cloudflare 中的 Secret 已保存并随新部署生效，再强制刷新管理页面并重新复制安装命令。若使用 GitHub Actions 部署，还要同步更新仓库 Actions Secret，避免下一次部署覆盖设置。

页面能打开，保存时出现 `Failed to fetch`#

打开浏览器开发者工具检查失败请求：

有 HTTP 状态码：根据 401、403、5xx 排查鉴权或 Worker 错误。
没有状态码并出现 ERR_NETWORK_CHANGED：通常是浏览器代理路径在请求期间发生切换。

同时使用浏览器代理扩展、系统代理、分流工具和 TUN 时，应让同一站点的 HTML、Fetch/XHR 与 WebSocket 走同一条稳定路径。可暂时关闭自动切换，逐层排除代理。

外部资源被浏览器拦截#

先在 Console 查看是否为 CSP 错误。仅将实际需要、可以信任的资源域名加入对应的 CSP Static 或 CSP API 白名单。

七、升级、备份与容量#

同步上游#

在 Fork 仓库选择 Sync fork → Update branch。部署完成后再观察 Worker 日志和 Agent 在线情况，不要把“同步成功”等同于“生产可用”。

升级 Agent#

优先使用管理后台当前版本给出的升级或重新安装命令。涉及 Agent 上报地址、Secret 或自动更新设置时，通常需要重新执行完整安装命令。

备份#

以下时机应导出服务器配置：

大版本升级前。
批量修改主机、分组或标签后。
迁移 Worker 或域名前。

导出文件也可能包含内部资产信息，应按敏感配置保管。

免费额度#

Cloudflare 配额会随套餐与官方政策变化，不应在教程中写死固定数值。以 Cloudflare Dashboard 和官方文档为准；机器增加时优先降低上报频率、减少 Ping 目标并控制历史数据量。

八、验收清单#

Worker 构建与生产部署成功。
API_SECRET 已设置且未出现在仓库或截图中。
管理员密码与 Agent Secret 不同。
每台主机的 cf-probe 服务正常。
管理后台持续收到 CPU、内存、磁盘和网络数据。
告警时区、通知目标和流量重置日正确。
外部资源仅使用最小 CSP 白名单。
已导出一份服务器配置并安全保存。

参考资料#

Debian SSH 密钥登录排障与安全加固

Thu, 17 Sep 2026 00:00:00 GMT

Debian SSH 密钥登录排障与安全加固#

本文处理一种典型故障：Windows 客户端能读取 ED25519 私钥，服务器也保存了对应公钥，但 SSH 仍只允许密码认证。排查后发现 Debian 服务端的最终配置为 PubkeyAuthentication no。

最终目标#

1
Windows OpenSSH / KeePassXC Agent
2
        │ ED25519 公钥认证
3
        ▼
4
Debian VPS
5
├─ 普通管理用户登录
6
├─ 需要时通过 sudo 提权
7
├─ 禁止 root 远程登录
8
└─ 验证成功后关闭密码与交互式认证

Danger

修改 SSH 认证方式可能导致远程失联。全程保留一个已登录的管理会话，并确认云厂商控制台、VNC 或其他应急入口可用。

一、先确认本地密钥#

以下示例使用占位符：

1
管理用户：adminuser
2
服务器地址：203.0.113.10
3
SSH 端口：2222
4
私钥文件：server_ed25519

检查文件#

在 Windows PowerShell 执行：

Terminal window

1
Get-Item "$env:USERPROFILE\.ssh\server_ed25519*"

应至少包含：

1
server_ed25519       私钥，不可公开
2
server_ed25519.pub   公钥，可安装到服务器

比对公钥指纹#

Windows：

Terminal window

1
ssh-keygen -lf "$env:USERPROFILE\.ssh\server_ed25519.pub"

Debian：

Terminal window

1
ssh-keygen -lf /home/adminuser/.ssh/authorized_keys

指纹一致可以排除“安装了错误公钥”，但不能证明服务端允许公钥认证。

二、用客户端日志定位认证阶段#

强制只使用指定私钥：

Terminal window

1
ssh -vvv `
2
  -o IdentitiesOnly=yes `
3
  -i "$env:USERPROFILE\.ssh\server_ed25519" `
4
  -p 2222 `
5
  adminuser@203.0.113.10

关键日志：

1
Offering public key
2
Server accepts key
3
Authenticated ... using "publickey"

若客户端已经列出待尝试密钥，但服务端返回的可用认证方式只有 password，并且从未出现 Offering public key，应优先检查服务端是否关闭了公钥认证。

以下信息通常不是根因：

用户级 .ssh/config 不存在。
显式使用 -i 时，客户端无法连接 ssh-agent。
登录成功后仍显示 debug3：这是 -vvv 调试输出。
Debian 中没有 ll：它只是未定义该 alias。

三、确认 Debian 的最终生效配置#

查看全局最终值：

Terminal window

1
sudo /usr/sbin/sshd -T | grep -Ei \
2
'pubkeyauthentication|passwordauthentication|kbdinteractiveauthentication|authorizedkeysfile|authenticationmethods|permitrootlogin|usepam'

再查找配置来源：

Terminal window

1
sudo grep -RniE \
2
'^[[:space:]]*(Include|PubkeyAuthentication|PasswordAuthentication|KbdInteractiveAuthentication|AuthorizedKeysFile|AuthenticationMethods|PermitRootLogin|Match)[[:space:]]' \
3
/etc/ssh/sshd_config /etc/ssh/sshd_config.d 2>/dev/null

若存在 Match 条件块，用实际连接条件检查：

Terminal window

1
sudo /usr/sbin/sshd -T \
2
  -C user=adminuser,host=server.example,addr=198.51.100.25 \
3
  | grep -Ei 'pubkeyauthentication|passwordauthentication|kbdinteractiveauthentication|permitrootlogin'

Important

OpenSSH 对多数配置项采用“首次取得的值生效”。Include 文件按字典序加载，因此不要简单地把重复配置追加到主文件末尾；必须以 sshd -T 的结果为准。

四、先恢复公钥认证#

本节只开启公钥认证，暂时保留原有密码和 root 登录作为回退。

备份配置#

Terminal window

1
sudo cp -a /etc/ssh/sshd_config \
2
  /etc/ssh/sshd_config.before-pubkey
3

4
sudo cp -a /etc/ssh/sshd_config.d \
5
  /etc/ssh/sshd_config.d.before-pubkey

确认主配置包含位于认证设置之前的：

1
Include /etc/ssh/sshd_config.d/*.conf

然后创建本地管理文件：

Terminal window

1
sudoedit /etc/ssh/sshd_config.d/00-local-auth.conf

第一阶段只写：

1
PubkeyAuthentication yes

如果当前系统不加载 sshd_config.d，应编辑前一步查到的实际配置来源，而不是继续写一个不会被读取的文件。

语法与最终值检查#

Terminal window

1
sudo /usr/sbin/sshd -t
2
sudo /usr/sbin/sshd -T | grep -Ei \
3
'permitrootlogin|passwordauthentication|kbdinteractiveauthentication|pubkeyauthentication'

sshd -t 无输出代表语法检查通过。只有当最终值显示：

1
pubkeyauthentication yes

才重新加载服务：

Terminal window

1
sudo systemctl reload ssh

不要先停止 ssh 服务，也不要关闭当前会话。

五、在第二个窗口验证密钥登录#

新开 PowerShell：

Terminal window

1
ssh -vvv `
2
  -o IdentitiesOnly=yes `
3
  -i "$env:USERPROFILE\.ssh\server_ed25519" `
4
  -p 2222 `
5
  adminuser@203.0.113.10

验证身份和提权：

Terminal window

1
whoami
2
sudo -v
3
sudo whoami

输入项不要混淆：

提示	应输入的内容
`Enter passphrase for key`	本地 SSH 私钥口令
`[sudo] password for adminuser`	Debian 普通用户密码
SSH 密码认证提示	Debian 登录用户密码

Linux 输入 sudo 密码时不会显示字符或星号，这是正常行为。

六、确认密钥稳定后收紧认证#

只有以下条件全部满足才能继续：

第二个独立窗口已通过密钥登录普通用户。
sudo whoami 返回 root。
原有管理会话仍保持连接。
应急控制台可用。

编辑：

Terminal window

1
sudoedit /etc/ssh/sshd_config.d/00-local-auth.conf

设置：

1
PubkeyAuthentication yes
2
PasswordAuthentication no
3
KbdInteractiveAuthentication no
4
PermitRootLogin no

再次检查：

Terminal window

1
sudo /usr/sbin/sshd -t
2
sudo /usr/sbin/sshd -T | grep -Ei \
3
'permitrootlogin|passwordauthentication|kbdinteractiveauthentication|pubkeyauthentication'

目标结果：

1
permitrootlogin no
2
pubkeyauthentication yes
3
passwordauthentication no
4
kbdinteractiveauthentication no

确认后重新加载：

Terminal window

1
sudo systemctl reload ssh

七、用第三个窗口做最终验收#

保持以下三个窗口：

1
窗口 A：修改前已登录的管理会话，用于回滚
2
窗口 B：第一次密钥登录成功的普通用户会话
3
窗口 C：重新加载后新开的最终测试会话

在窗口 C 登录：

Terminal window

1
ssh `
2
  -o IdentitiesOnly=yes `
3
  -i "$env:USERPROFILE\.ssh\server_ed25519" `
4
  -p 2222 `
5
  adminuser@203.0.113.10

再次执行：

Terminal window

1
whoami
2
sudo whoami

窗口 C 验证成功后才能关闭窗口 A。

反向验证密码认证已关闭#

Terminal window

1
ssh `
2
  -o PubkeyAuthentication=no `
3
  -o PreferredAuthentications=password `
4
  -p 2222 `
5
  adminuser@203.0.113.10

预期失败并返回类似：

1
Permission denied (publickey).

八、配置 SSH 别名#

在 Windows 当前用户的 .ssh\config 中写入：

1
Host server-a
2
    HostName 203.0.113.10
3
    Port 2222
4
    User adminuser
5
    IdentityFile ~/.ssh/server_ed25519
6
    IdentitiesOnly yes

以后使用：

Terminal window

1
ssh server-a

若私钥只保存在 KeePassXC、由 Agent 提供，可按 Windows 使用 KeePassXC 与 SSH Agent 管理 SSH 密钥#Agent 中密钥很多时的方式让 IdentityFile 指向对应公钥。

九、排障判断表#

现象	优先检查
本地私钥不存在	路径和文件名
两端公钥指纹不同	`authorized_keys` 是否贴错
服务端只提供 `password`	`sshd -T` 中的 `PubkeyAuthentication`
已出现 `Offering public key` 但失败	用户、文件权限、`AuthorizedKeysFile`、`Match` 规则
`Too many authentication failures`	`IdentitiesOnly` 与 Agent 中密钥数量
登录后持续出现 `debug3`	客户端仍带 `-vvv`
提示私钥 passphrase	输入本地私钥口令
提示 sudo 密码	输入 Debian 普通用户密码
Agent pipe 不存在	Agent 未运行；显式 `-i` 不受影响

十、公开前隐私检查#

发布教程、终端输出或截图前移除：

真实 VPS IP、端口、主机名和用户名。
SSH 私钥、完整公钥及指纹。
Last login 中的客户端出口 IP。
Windows 本地用户名和绝对路径。
代理节点 UUID、REALITY 密钥、short ID、订阅地址。
API Key、Cookie、Token 和安装命令中的 Secret。

验收清单#

本地公钥与服务器 authorized_keys 指纹一致。
sshd -T 显示 pubkeyauthentication yes。
普通用户可在新窗口通过密钥登录。
普通用户可正常执行 sudo。
sshd -t 语法检查通过。
重新加载后第三个窗口仍能登录。
PermitRootLogin no 已生效。
密码和交互式认证反向测试失败。
应急控制台和配置备份可用。

参考资料#

KeePassXC 推荐配置与使用指南

Tue, 15 Sep 2026 00:00:00 GMT

KeePassXC 推荐配置与使用指南#

Info

本文按 KeePassXC 2.7.12 简体中文界面整理。菜单名和选项名尽量使用软件中的实际中文名称，而不是自行翻译。适用场景：Windows 10/11、KeePassXC 作为主力、Chrome/Edge 浏览器、可与 KeePass 2.x 共用同一个 .kdbx。

相关笔记：KeePass 密码管理、电脑必备软件

官方下载：KeePassXC

1. 推荐配置速览#

1
KeePassXC
2
├─ 常规
3
│  ├─ 启动：自动启动、单实例、记住数据库
4
│  ├─ 文件管理：修改后自动保存、外部修改自动重新加载
5
│  ├─ 用户界面：任务栏图标、最小化到任务栏
6
│  └─ 自动输入：设置全局快捷键
7
├─ 安全
8
│  ├─ 剪贴板：10~15 秒清空
9
│  ├─ 闲置锁定：900~1800 秒
10
│  ├─ Windows Hello：开启快速解锁
11
│  ├─ Windows 锁屏时锁数据库
12
│  └─ 不建议“最小化窗口后锁定数据库”
13
├─ 浏览器集成
14
│  ├─ 开启 KeePassXC-Browser
15
│  ├─ 勾选实际使用的浏览器
16
│  ├─ 优先按真实 URL 匹配
17
│  └─ 不建议自动提交登录表单
18
├─ 数据库
19
│  ├─ KDBX 4
20
│  ├─ AES-256
21
│  ├─ Argon2id
22
│  ├─ 保留历史记录
23
│  └─ 开启回收站
24
└─ 可选增强
25
   ├─ TOTP
26
   ├─ Passkey
27
   ├─ SSH 代理
28
   ├─ 高级自定义字段
29
   └─ 数据库报告

展开收起

2. 工具 → 设置 → 常规#

打开：工具 → 设置 → 常规

2.1 启动#

位置：工具 → 设置 → 常规 → 启动

中文界面实际名称	推荐	说明
只启动一个 KeePassXC 实例	✅	避免重复打开多个实例
系统启动时自动启动 KeePassXC	✅	开机即运行
在应用程序启动时最小化窗口	可选	喜欢后台运行可开启
解锁数据库后最小化窗口	✅	解锁后自动回到后台
记住以前使用的数据库	✅	不必每次重新选 KDBX
启动时加载以前打开的数据库	✅	建议和上一项一起开
记住数据库密钥文件和安全加密狗	按需	只有使用 Key File / YubiKey 时才需要
每周在应用程序启动时检查更新	✅	保持版本更新
检查更新时包含 Beta 版本	❌	日常主力机不建议

2.2 文件管理#

位置：工具 → 设置 → 常规 → 文件管理

中文界面实际名称	推荐	说明
修改后自动保存	✅	很重要
锁定数据库时自动保存	✅	避免未保存修改
锁定数据库时，自动保存非数据更改	✅	推荐
有外部修改时自动重新加载数据库	✅	与 KeePass/同步盘共用时尤其有用
保存前备份数据库文件	✅ 可开	会额外保留旧数据库
使用替代保存方式	默认关闭	云盘保存异常时再考虑

如必须启用“使用替代保存方式”，优先：

写入临时文件再覆盖移动

不要主动使用：

直接写入数据库文件（危险）

Warning

若 KeePass 与 KeePassXC 共用同一个 .kdbx，建议开启“修改后自动保存”和“有外部修改时自动重新加载数据库”，但仍不要让两个程序长期同时编辑同一个数据库。外部修改自动重新加载不等于自动安全合并。

2.3 条目管理#

位置：工具 → 设置 → 常规 → 条目管理

推荐：

✅ 新增条目时使用群组图标
✅ 删除条目到回收站之前提示确认
✅ 在条目视图中，双击字段复制数据
✅ 为新条目自动生成密码
“打开 URL 时最小化”按习惯
“复制到剪贴板时隐藏窗口”按习惯

2.4 用户界面#

位置：工具 → 设置 → 常规 → 用户界面

推荐：

✅ 显示任务栏图标
✅ 将窗口最小化至任务栏
✅ 最小化而不是退出应用程序
“备注使用等宽字体”开发用途推荐
“密码以彩色显示”按喜好

3. 工具 → 设置 → 安全#

打开：工具 → 设置 → 安全

3.1 超时#

位置：工具 → 设置 → 安全 → 超时

在多久后清空剪贴板#

推荐：10~15 秒，建议 15 秒。

如果主要使用 KeePassXC-Browser，密码经过剪贴板的次数会明显减少。

在多久后清空搜索框#

在闲置多久后锁定数据库#

单位是秒。

推荐：

1
900 秒  = 15 分钟
2
1800 秒 = 30 分钟

建议从 900 秒 开始。

Note

这里的“闲置”主要是 KeePassXC 自身的活动判断，不等于 Windows 整台电脑完全没有键盘鼠标操作。

3.2 便利性#

位置：工具 → 设置 → 安全 → 便利性

建议开启：

启用数据库快速解锁（Touch ID / Windows Hello）

典型流程：

1
KeePassXC 启动
2
→ 首次输入数据库主密码
3
→ 后续数据库自动锁定
4
→ Windows Hello 快速解锁

Windows Hello 主要用于后续快速解锁，不能取代数据库主密码本身。

3.3 锁定选项#

位置：工具 → 设置 → 安全 → 锁定选项

推荐：

1
☑ 系统锁定或合上盖子时锁定数据库
2
☑ 切换用户时锁定数据库
3
☐ 在最小化窗口后锁定数据库

不建议“在最小化窗口后锁定数据库”，尤其如果已经开启“解锁数据库后最小化窗口”。

3.4 隐私#

位置：工具 → 设置 → 安全 → 隐私

推荐：

1
☑ 编辑密码时隐藏密码
2
☑ 在条目预览面板中隐藏密码
3
☑ 在条目预览面板隐藏 TOTP
4
☑ 在条目预览面板隐藏备注

“使用 DuckDuckGo 来下载网站图标”按隐私偏好决定。

4. 浏览器自动填充#

4.1 安装 KeePassXC-Browser#

安装官方扩展：KeePassXC-Browser

支持 Chrome、Edge、Chromium、Brave、Vivaldi、Firefox。

4.2 KeePassXC 中开启浏览器集成#

位置：工具 → 设置 → 浏览器集成

开启：

1
☑ 启用浏览器集成

然后在“为这些浏览器开启集成”中勾选实际使用的浏览器，例如：

1
☑ Google Chrome
2
☑ Edge

推荐同时开启：

1
☑ 如果数据库已锁定，则请求解锁

“请求凭据时显示通知”按个人喜好。

4.3 第一次连接数据库#

保证数据库已经解锁：

1
浏览器
2
→ KeePassXC-Browser
3
→ Connect / 连接

连接名称建议：

1
Chrome-Home-PC
2
Edge-Home-PC
3
Chrome-Work-PC

避免不同设备重复使用完全相同的连接名。

5. 条目的浏览器 URL 匹配#

编辑条目：条目 → 浏览器集成

主 URL 在条目首页，例如：

1
https://github.com

同一账号用于多个地址时，在“浏览器集成”添加额外 URL，例如：

1
https://login.example.com
2
https://account.example.com

KeePassXC 2.7.10+ 支持额外 URL 通配符：

1
https://*.example.com
2
https://example.com/*/login
3
https://sub.*.example.com/path/*

推荐原则：

1
网页 → KeePassXC-Browser → 按真实 URL 匹配
2
桌面程序 → Auto-Type / 窗口标题匹配

不要再把网页窗口标题匹配当作浏览器密码匹配主方案。

6. 浏览器扩展中的自动填充策略#

推荐：

1
✅ 自动获取可用凭据
2
❌ 不建议页面打开就无条件自动填单一账号
3
❌ 不建议自动提交登录表单
4
TOTP 自动填充：按个人习惯

日常流程：

1
打开登录页
2
→ 输入框出现 KeePassXC 图标
3
→ 点击账号
4
→ 填入用户名和密码
5
→ 需要 TOTP 时继续填 TOTP

不建议默认开启“自动提交”，避免误填、误登录或特殊网页识别错误。

7. 自动输入 Auto-Type#

Auto-Type 与浏览器集成是两套独立功能。

推荐用途：

1
网页       → KeePassXC-Browser
2
桌面程序   → Auto-Type
3
远程工具   → Auto-Type
4
旧式登录框 → Auto-Type

7.1 设置全局 Auto-Type 快捷键#

位置：工具 → 设置 → 自动输入

找到：全局自动输入快捷键

例如：

1
Ctrl + Alt + A

建议：

1
☑ 全局自动输入时使用条目标题匹配窗口
2
☑ 总在执行自动输入前询问

同页还能设置：

全局自动输入时使用条目 URL 匹配窗口
自动输入时隐藏已过期条目
自动输入起始延迟
自动输入延迟

7.2 给单个条目配置窗口标题#

编辑条目：条目 → 自动输入

窗口规则：

1
*GitHub*
2
*Oracle*

* 是通配符。

正则示例：

1
//^Secure Login - .*//

默认输入序列：

1
{USERNAME}{TAB}{PASSWORD}{ENTER}

需要 TOTP：

1
{USERNAME}{TAB}{PASSWORD}{ENTER}
2
{DELAY 1000}
3
{TOTP}{ENTER}

KeePassXC 2.7.12 也支持 {TIMEOTP}。

8. TOTP#

8.1 添加#

对条目右键：TOTP → 设置 TOTP

填入网站提供的原始 Secret。

绝大多数网站：

1
周期：30 秒
2
位数：6
3
算法：SHA-1

8.2 使用#

Ctrl + T：复制当前 TOTP。

Ctrl + Y：复制 Password + TOTP。

也可通过：

KeePassXC-Browser
Auto-Type {TOTP}
条目右键菜单

8.3 安全取舍#

方便模式：

1
同一个 KDBX
2
├─ 密码
3
└─ TOTP Secret

隔离更强：

1
KeePassXC → 密码
2
独立 Authenticator → TOTP

与 KeePass 共用同一个 KDBX 时：KeePassXC 保存的 TOTP 不会导致数据库无法打开，但 KeePass 不一定自动识别成自己的 TOTP 字段。若 KeePassXC 已成为主力，建议主要由 KeePassXC 管理 TOTP。

9. Passkey#

KeePassXC 可以通过 KeePassXC-Browser 保存 Passkey。

Warning

KeePassXC 2.7.12 调整了 Passkey 的 BE/BS 标志。极少数更早版本创建的旧 Passkey 如果升级后异常，需要单独处理；新建 Passkey 无需额外配置。

建议：

新建 Passkey 可以直接用 KeePassXC
重要账号仍保存 Recovery Codes
不要把 Recovery Codes 只保存在唯一一个 KDBX 中

10. 条目中的“高级”#

编辑条目：条目 → 高级

用途：

自定义属性
额外账号字段
API 信息
附件
特殊集成数据

示例：

1
标题：Example VPS
2
用户名：root
3
密码：********
4
URL：ssh://example.com
5

6
高级：
7
IP             203.0.113.10
8
SSH-Port       22
9
Panel-User     admin
10
Panel-Password ********
11
Client-ID      example-id

引用自定义字段：

1
{S:字段名}

例如：

1
{S:API_KEY}

11. 浏览器特殊表单字段#

企业系统常见额外字段：

1
租户号
2
公司编码
3
Account ID
4
PIN

可在“高级”中建立字段，再由 KeePassXC-Browser 选择网页对应输入框。不标准的登录页也可以使用 KPH: 自定义字段，然后在扩展中绑定网页输入框。

12. 密码生成器#

推荐：

1
长度：20~32
2
大写：开启
3
小写：开启
4
数字：开启
5
特殊字符：开启

核心原则：

1
每个网站独立随机密码

浏览器注册或改密码时，可直接调用 KeePassXC-Browser 密码生成器并保存到数据库。

13. 数据库设置#

打开：数据库 → 数据库设置

这是当前 KDBX 的设置，不是 KeePassXC 全局设置。

13.1 常规#

推荐：

1
☑ 回收站
2
☑ 压缩

历史记录建议保留，但不要无限增长。经验值：

1
历史条目数量：约 10
2
历史大小：约 6 MiB

13.2 安全 / 加密设置#

推荐：

1
数据库格式：KDBX 4
2
加密算法：AES-256
3
KDF：Argon2id

利用基准测试把解锁耗时设在大约 1 秒 即可，不必手工折腾 Iterations、Memory、Parallelism。

与 KeePass 共库时，如果还使用很旧的 KeePass、老插件或老手机客户端，修改 KDF 前先确认兼容性。

14. 数据库 → 浏览器集成#

位置：数据库 → 数据库设置 → 浏览器集成

这里用于当前数据库级管理，可进行：

断开与所有浏览器的关联
转换旧 KeePassHTTP 数据
刷新数据库根群组 ID
管理数据库浏览器相关设置

日常无需频繁操作。

15. 群组级浏览器控制#

编辑群组：群组 → 浏览器集成

可设置：

在浏览器扩展中隐藏条目

适合：

1
SSH Keys
2
API Tokens
3
Recovery Codes
4
内部凭据

16. 数据库报告#

打开：数据库 → 数据库报告

建议关注：

健康检查：弱密码、重复密码、过期密码
HIBP：检查公开泄漏
浏览器统计：排查某网站为什么不显示凭据

建议每 2~3 个月做一次健康检查。HIBP 属于在线检查，不必频繁运行。

17. SSH 代理#

适合 GitHub、GitLab、VPS、Linux 服务器。

完整配置与排障步骤见：Windows 使用 KeePassXC 与 SSH Agent 管理 SSH 密钥。

KeePassXC 不是 SSH Agent 本身，而是现有 SSH Agent 的客户端。

17.1 Windows 启用 OpenSSH Authentication Agent#

管理员 PowerShell：

Terminal window

1
Get-Service ssh-agent | Set-Service -StartupType Automatic
2
Start-Service ssh-agent

17.2 KeePassXC 开启#

位置：工具 → 设置 → SSH 代理

开启：

1
☑ 启用 SSH 代理集成
2
☑ 使用 OpenSSH

若显示“SSH 代理连接工作正常！”，说明连接成功。

17.3 条目配置 SSH Key#

编辑条目：

1
条目 → 高级 → 添加私钥附件
2
条目 → SSH 代理 → 选择对应私钥

可配置数据库解锁时自动加载、锁定时移除等。之后可减少 git pull、git push、ssh user@example.com 过程中反复输入私钥密码的次数。

18. 数据库同步与备份#

KDBX 可放在 OneDrive、Dropbox、Google Drive、Nextcloud、Syncthing、NAS。

推荐：

1
OneDrive
2
└─ KeePass
3
   └─ passwords.kdbx

最好选带版本历史的同步服务。

同步 ≠ 备份。

至少建议：

1
主 KDBX
2
+
3
云盘版本历史
4
+
5
偶尔离线备份

如果使用 Key File，不要把它和 .kdbx 放在同一个云盘同一位置。出现冲突副本时，可使用：

数据库 → 从数据库合并

19. KeePass + KeePassXC 共用一个 KDBX#

基本兼容：

1
账号 / 密码 / URL / 备注
2
→ 两边正常使用

19.1 TOTP#

KeePassXC 与 KeePass 原生 TOTP 的内部字段格式不完全一致。

结果：

1
KeePassXC 添加 TOTP
2
→ KeePass 能正常打开数据库
3
→ 但不一定自动识别成 KeePass 自己的 TOTP

不会因此破坏整个 KDBX。

如果 KeePassXC 已成为主力，建议 TOTP 主要由 KeePassXC 管理。

19.2 Passkey#

Passkey 更偏 KeePassXC 自己的浏览器集成，建议主要让 KeePassXC 管理。不要假设 KeePass 能直接使用。

19.3 自定义字段#

KeePass 通常可以保留 KeePassXC 创建的普通自定义字段。

但重要数据库升级前仍建议备份。

推荐使用方式：

1
KeePassXC = 主力，长期运行
2
KeePass = 兼容 / 备用，用完关闭

20. 不建议为了“高级”强行开启的功能#

Key File#

能增强安全性，但会增加备份、多设备同步和遗失风险。没有明确需求时不用强开。

YubiKey#

支持 Challenge-Response，但必须认真准备备用硬件和恢复方案，否则硬件损坏或丢失可能导致数据库无法解锁。

当前更推荐：

1
强主密码
2
+ Windows Hello 快速解锁
3
+ KDBX 多份备份

除非确实有更高安全需求，再增加第二解锁因素。

21. 截图保护#

KeePassXC 在 Windows 上支持阻止普通截图/录屏捕获敏感窗口。

临时需要截图时：

查看 → 允许屏幕截图

涉及主密码、TOTP Secret、Recovery Code、私钥、API Token 时不要随意截图。使用后及时关闭。

22. 推荐快捷键#

操作	快捷键
搜索	`Ctrl + F`
编辑条目	`Enter` / `Ctrl + E`
新建条目	`Ctrl + N`
复制用户名	`Ctrl + B`
复制密码	`Ctrl + C`
复制 URL	`Ctrl + U`
复制 TOTP	`Ctrl + T`
Password + TOTP	`Ctrl + Y`
Auto-Type	`Ctrl + Shift + V`
锁定当前数据库	`Ctrl + L`
数据库报告	`Ctrl + Shift + R`
设置	`Ctrl + ,`

全局 Auto-Type 快捷键建议自行设置，例如：

1
Ctrl + Alt + A

23. 最终推荐配置清单#

工具 → 设置 → 常规#

1
启动
2
☑ 只启动一个 KeePassXC 实例
3
☑ 系统启动时自动启动 KeePassXC
4
☑ 记住以前使用的数据库
5
☑ 启动时加载以前打开的数据库
6
☑ 解锁数据库后最小化窗口
7
☑ 每周在应用程序启动时检查更新
8
☐ 检查更新时包含 Beta 版本
9

10
文件管理
11
☑ 修改后自动保存
12
☑ 锁定数据库时自动保存
13
☑ 锁定数据库时，自动保存非数据更改
14
☑ 有外部修改时自动重新加载数据库
15
☑ 保存前备份数据库文件（可选但推荐）
16

17
用户界面
18
☑ 显示任务栏图标
19
☑ 将窗口最小化至任务栏
20
☑ 最小化而不是退出应用程序

展开收起

工具 → 设置 → 安全#

1
超时
2
在多久后清空剪贴板：15 秒
3
在闲置多久后锁定数据库：900 秒
4

5
便利性 / 锁定选项
6
☑ 启用数据库快速解锁（Touch ID / Windows Hello）
7
☑ 系统锁定或合上盖子时锁定数据库
8
☑ 切换用户时锁定数据库
9
☐ 在最小化窗口后锁定数据库
10

11
隐私
12
☑ 编辑密码时隐藏密码
13
☑ 在条目预览面板中隐藏密码
14
☑ 在条目预览面板隐藏 TOTP
15
☑ 在条目预览面板隐藏备注

展开收起

工具 → 设置 → 浏览器集成#

1
☑ 启用浏览器集成
2
☑ Google Chrome（如果使用）
3
☑ Edge（如果使用）
4
☑ 如果数据库已锁定，则请求解锁

数据库#

1
KDBX 4
2
AES-256
3
Argon2id
4
KDF 基准约 1 秒
5

6
☑ 回收站
7
☑ 压缩
8
保留合理数量的历史记录

24. 当前版本说明#

本文基于：

1
KeePassXC 2.7.12
2
简体中文
3
Windows

如果以后升级到 2.8.x 或更高版本，菜单结构和中文翻译可能变化，应重新核对实际软件界面。

参考依据#

KeePassXC Documentation
KeePassXC User Guide
KeePassXC Getting Started：Browser Integration
KeePassXC User Guide：SSH Agent
KeePassXC GitHub Repository
KeePassXC 2.7.12 官方简体中文翻译文件
KeePassXC 2.7.12 Release Notes

用一台美国 VPS 搭建 AI 专用出口：Xray REALITY + FlClash + Mihomo 动态 AI 分流

Fri, 11 Sep 2026 00:00:00 GMT

用一台美国 VPS 搭建 AI 专用出口：Xray REALITY + FlClash + Mihomo 动态 AI 分流#

这篇教程解决什么问题

用一台 Debian VPS 自建 VLESS + REALITY + Vision 出口，并在 Windows / Android 的 FlClash（Mihomo） 中做精细分流：

ChatGPT / Claude / Gemini / Grok 以及 Cursor、Copilot、Perplexity、OpenRouter 等海外 AI 服务走固定 VPS；
普通网站继续走原来的机场/代理；
Android 上用 App 包名兜底，避免 ChatGPT、Claude、Gemini、Grok 的 Sentry、Datadog、NTP 等辅助请求漏到其他出口；
使用社区维护的 category-ai-!cn 动态规则集，减少手工维护几十个域名；
VPS 仍保留为“机场故障时的手动应急出口”，但不参加机场自动测速组。

本文是已实际跑通过的阶段性方案整理版。为了可以公开发布，所有真实 IP、SSH 端口、UUID、REALITY 私钥/公钥、Short ID、机场节点名、订阅地址等均已替换为占位符。

服务器密钥登录和关闭密码认证的后续步骤见：Debian SSH 密钥登录排障与安全加固。

0. 先看最终架构#

AI App 包名

category-ai-!cn

普通国外网站

国内 / 内网

Windows / Android

FlClash / Mihomo

AI 专线策略组

机场主策略组

DIRECT

VLESS + REALITY + Vision

美国 VPS

ChatGPT / Claude / Gemini / Grok / Cursor / Copilot...

AI App 包名

category-ai-!cn

普通国外网站

国内 / 内网

Windows / Android

FlClash / Mihomo

AI 专线策略组

机场主策略组

DIRECT

VLESS + REALITY + Vision

美国 VPS

ChatGPT / Claude / Gemini / Grok / Cursor / Copilot...

核心思想不是“全局都走 VPS”，而是：

1
AI / AI 编程工具
2
        ↓
3
固定 VPS 出口
4

5
普通外网
6
        ↓
7
机场
8

9
国内 / 内网
10
        ↓
11
DIRECT

这样做的好处是：需要固定出口的 AI 服务尽量保持一致，而视频、下载、GitHub Release、普通网页等流量不会无意义占用 VPS 带宽。

1. 隐私与安全：公开教程前一定先做脱敏#

下面这些内容绝对不要发布到 GitHub、论坛、博客、截图或群聊：

内容	是否可公开
VPS 厂商、套餐名称	一般可以
操作系统、CPU、内存	可以
VPS 真实公网 IP	建议隐藏
SSH 真实端口	建议隐藏
VLESS UUID	不公开
REALITY `privateKey`	绝对不公开
REALITY 客户端公钥 / `public-key`	不建议公开
`short-id`	不建议公开
VLESS 分享链接 / 二维码	等同访问凭据，不公开
机场订阅地址	绝对不公开
机场节点名、套餐信息	没必要公开
API Key / Cookie / Token	绝对不公开

本文统一使用：

1
REPLACE_VPS_IP
2
REPLACE_SSH_PORT
3
REPLACE_UUID
4
REPLACE_PRIVATE_KEY
5
REPLACE_CLIENT_PUBLIC_KEY
6
REPLACE_SHORT_ID

Warning

REALITY 的服务端 PrivateKey 只存在 VPS 服务端。不要放进 FlClash，不要放进二维码，也不要为了求助把它截图发出来。

2. 环境说明#

本文以以下环境为例：

VPS：美国节点；
系统：Debian 12；
架构：x86_64 / amd64；
内存：1 GB 也可运行；
Xray：官方安装脚本；
协议：VLESS + REALITY + XTLS Vision；
公网入口：TCP 443；
Windows / Android 客户端：FlClash；
FlClash 核心：Mihomo。

如果你的 VPS 已经跑着 Docker、Nginx、Caddy、面板或其他服务，不要直接照抄防火墙和 443 配置，先确认端口没有冲突：

Terminal window

1
ss -lntup

第一部分：VPS 基础配置#

3. 第一次登录后先做盘点#

以下命令在 VPS 的 Bash/SSH 终端执行：

Terminal window

1
cat /etc/os-release
2
uname -r
3
uname -m
4
free -h
5
df -hT /
6
swapon --show
7
ip -br addr
8
ip route
9
ss -lntup
10
timedatectl

重点确认：

系统确实是你预期的 Debian；
架构是不是 x86_64；
443 是否已被其他程序占用；
当前有没有 Swap；
时间是否正确。

4. 更新 Debian 与安装基础工具#

Terminal window

1
apt update
2
apt upgrade
3

4
apt install ca-certificates curl wget nano unzip jq openssl sudo ufw \
5
  htop mtr-tiny dnsutils iproute2 iputils-ping systemd-timesyncd \
6
  unattended-upgrades debian-security-support
7

8
systemctl enable --now systemd-timesyncd
9
timedatectl status

如果系统升级涉及内核，完成更新后可以安排一次重启：

Terminal window

1
reboot

重连后确认：

Terminal window

1
uname -r

5. 1 GB 小内存 VPS：没有 Swap 时加 1 GB#

先检查：

Terminal window

1
swapon --show
2
df -hT /

只有没有 Swap 时才执行：

Terminal window展开收起

1
if [ -z "$(swapon --noheadings --show)" ] && \
2
   [ ! -e /swapfile ] && ! grep -qE '^/swapfile[[:space:]]' /etc/fstab; then
3

4
  if fallocate -l 1G /swapfile && \
5
     chmod 600 /swapfile && \
6
     mkswap /swapfile && \
7
     swapon /swapfile; then
8

9
    printf '/swapfile none swap sw 0 0\n' >> /etc/fstab
10
    printf 'vm.swappiness=10\n' > /etc/sysctl.d/90-ai-memory.conf
11
    sysctl -p /etc/sysctl.d/90-ai-memory.conf
12
    swapon --show
13
  else
14
    echo 'Swap 创建失败，请检查文件系统和剩余空间。'
15
  fi
16
else
17
  echo '检测到已有 Swap 或旧配置，跳过。'
18
fi

展开收起

这个配置的目的不是让 1 GB VPS 变成 2 GB 内存，而是避免某些瞬时内存峰值直接触发 OOM。

6. UFW：只开放 SSH 与 Xray 443#

Danger

先确认 VPS 厂商控制台/VNC/救援入口可用，并确认真实 SSH 端口。 写错 SSH 规则可能把自己锁在服务器外面。

查看当前状态：

Terminal window

1
ufw status verbose
2
ss -lntp

将 REPLACE_SSH_PORT 换成你自己的 SSH 端口：

Terminal window

1
ufw default deny incoming
2
ufw default allow outgoing
3

4
ufw allow REPLACE_SSH_PORT/tcp comment 'SSH management'
5
ufw allow 443/tcp comment 'Xray REALITY'
6

7
ufw enable
8
ufw status numbered

这套方案不需要把本地代理端口、数据库端口或未来的监控面板端口直接暴露到公网。

7. 限制 systemd 日志体积#

小硬盘 VPS 没必要让日志无限增长：

Terminal window

1
mkdir -p /etc/systemd/journald.conf.d
2

3
cat > /etc/systemd/journald.conf.d/90-ai-vps.conf <<'EOF'
4
[Journal]
5
SystemMaxUse=100M
6
RuntimeMaxUse=50M
7
MaxRetentionSec=7day
8
EOF
9

10
systemctl restart systemd-journald
11
journalctl --disk-usage

正常运行时，Xray 日志保持 warning / error 即可。排障时可以临时开 debug，但解决后记得恢复。

第二部分：安装 Xray + REALITY#

8. 使用 Xray 官方安装器#

不要从不明网盘或“一键整合包”下载安装。

Terminal window

1
install -d -m 700 /opt/ai-vps-setup
2
cd /opt/ai-vps-setup
3

4
curl -fL --proto '=https' --tlsv1.2 \
5
  https://raw.githubusercontent.com/XTLS/Xray-install/main/install-release.sh \
6
  -o install-xray.sh
7

8
less install-xray.sh
9
sha256sum install-xray.sh
10
bash install-xray.sh help

安装时建议先查看 Xray 官方 Releases，再固定一个你确认过的稳定版本。

示例：

Terminal window

1
bash install-xray.sh install --version REPLACE_XRAY_VERSION --without-geodata
2

3
/usr/local/bin/xray version
4
systemctl cat xray

本文的显式分流不依赖 Xray 的 geoip/geosite 文件，因此服务端可以不安装 geodata。

9. 生成 VLESS / REALITY 参数#

在 VPS 上执行：

Terminal window

1
/usr/local/bin/xray uuid
2
/usr/local/bin/xray x25519
3
openssl rand -hex 8

你会得到几类信息：

参数	用途
UUID	服务端和客户端都要填
PrivateKey	只放服务端
Password / 旧版显示的 PublicKey	客户端使用；Mihomo 字段仍叫 `public-key`
Short ID	服务端 `shortIds` 与客户端 `short-id` 对应

建议立即存进密码管理器，不要靠聊天记录保存。

10. REALITY 目标域名不要照抄，必须先测试#

REALITY 不是“随便填一个大网站域名”。

官方文档中，target 是服务端必填项，serverNames 通常应与目标返回证书可接受的 SNI 保持一致。

先测试候选：

Terminal window

1
/usr/local/bin/xray tls ping www.bing.com
2

3
curl -I --http2 \
4
  --connect-timeout 10 \
5
  --max-time 20 \
6
  https://www.bing.com/
7

8
openssl s_client \
9
  -connect www.bing.com:443 \
10
  -servername www.bing.com \
11
  -tls1_3 \
12
  -alpn h2 \
13
  </dev/null

本文实际排障过程中，某个最初候选在客户端 REALITY 握手阶段表现不稳定，换成经过 VPS 实测正常的 www.bing.com 后恢复。因此：

不要迷信“网上大家都用的 SNI”。你的 VPS 能稳定握手才是标准。

如果你选择其他域名：

1
服务端 target      → 域名:443
2
服务端 serverNames → 域名
3
客户端 servername  → 同一个域名

11. Xray 服务端配置模板#

编辑：

Terminal window

1
nano /usr/local/etc/xray/config.json

可使用下面的公开占位模板：

1
{
2
  "log": {
3
    "loglevel": "warning"
4
  },
5

6
  "inbounds": [
7
    {
8
      "listen": "0.0.0.0",
9
      "port": 443,
10
      "protocol": "vless",
11

12
      "settings": {
13
        "clients": [
14
          {
15
            "id": "REPLACE_UUID",
16
            "flow": "xtls-rprx-vision"
17
          }
18
        ],
19
        "decryption": "none"
20
      },
21

22
      "streamSettings": {
23
        "network": "raw",
24
        "security": "reality",
25

26
        "realitySettings": {
27
          "show": false,
28
          "target": "www.bing.com:443",
29
          "xver": 0,
30

31
          "serverNames": [
32
            "www.bing.com"
33
          ],
34

35
          "privateKey": "REPLACE_PRIVATE_KEY",
36

37
          "shortIds": [
38
            "REPLACE_SHORT_ID"
39
          ]
40
        }
41
      }
42
    }
43
  ],
44

45
  "outbounds": [
46
    {
47
      "protocol": "freedom",
48
      "tag": "direct"
49
    },
50
    {
51
      "protocol": "blackhole",
52
      "tag": "block"
53
    }
54
  ]
55
}

展开收起

检查配置：

Terminal window

1
/usr/local/bin/xray run \
2
  -test \
3
  -config /usr/local/etc/xray/config.json

没有错误后：

Terminal window

1
systemctl enable xray
2
systemctl restart xray
3

4
systemctl status xray --no-pager
5
ss -lntp | grep ':443'
6
journalctl -u xray -n 50 --no-pager

Windows 可以先只验证 TCP 端口：

Terminal window

1
Test-NetConnection REPLACE_VPS_IP -Port 443

TCP 443 能连上只代表“端口通”，不能证明 UUID、REALITY 公钥、Short ID、SNI 都正确。

第三部分：FlClash 添加 VPS 节点#

12. 为什么使用 FlClash#

FlClash 是基于 Clash.Meta / Mihomo 的多平台客户端，可以在 Windows、Android 等平台使用。

本文不要求你把原机场订阅扔掉，而是：

1
原机场订阅
2
   +
3
自己注入一条 VLESS REALITY 节点
4
   +
5
覆写脚本做 AI 分流

这样机场更新节点时，不需要手工重新拼一份完整 YAML。

13. Mihomo / FlClash 的 VLESS REALITY 节点模板#

下面这段不是完整配置，而是覆写脚本里要注入的一个节点对象：

1
const VPS_NODE_NAME = "AI-VPS";
2

3
const aiVpsProxy = {
4
  name: VPS_NODE_NAME,
5

6
  type: "vless",
7

8
  server: "REPLACE_VPS_IP",
9
  port: 443,
10

11
  uuid: "REPLACE_UUID",
12

13
  network: "tcp",
14
  tls: true,
15
  udp: true,
16

17
  "packet-encoding": "xudp",
18
  flow: "xtls-rprx-vision",
19

20
  servername: "www.bing.com",
21
  "client-fingerprint": "chrome",
22

23
  "reality-opts": {
24
    "public-key": "REPLACE_CLIENT_PUBLIC_KEY",
25
    "short-id": "REPLACE_SHORT_ID"
26
  },
27

28
  smux: {
29
    enabled: false
30
  }
31
};

展开收起

注意：

Xray 新版 x25519 可能把客户端公钥显示成 Password；
Mihomo 客户端字段仍然叫 public-key；
这里永远不会出现服务端 PrivateKey。

第四部分：AI 动态规则集，而不是手工写几十个域名#

14. 为什么不用纯手工域名#

AI 服务会使用：

主站；
API；
CDN；
登录认证；
上传下载；
遥测；
语音 / WebRTC；
云厂商依赖。

例如一个 ChatGPT App 请求不一定全是 openai.com，可能还会出现 Sentry、Datadog、LiveKit 等。

如果看到一个域名就手工补一个：

1
漏一个 → 加一个
2
再漏一个 → 再加一个

维护成本会越来越高。

更好的办法是使用社区持续维护的规则数据，再加少量本地兜底。

15. 使用 MetaCubeX `category-ai-!cn`#

本文选择：

1
MetaCubeX/meta-rules-dat
2
geo/geosite/category-ai-!cn.mrs

这个分类不仅包含：

OpenAI / ChatGPT；
Anthropic / Claude；
Google DeepMind / Gemini；
xAI / Grok；

还会包含部分：

Cursor；
GitHub Copilot；
Perplexity；
OpenRouter；
JetBrains AI；
Windsurf；
Hugging Face；
Poe；
Mistral；
Meta AI；
其他海外 AI 服务。

如果你的目标就是“海外 AI 统一走这台固定 VPS”，这比只维护四家域名更省心。

如果你只想让 ChatGPT / Claude / Gemini / Grok 四家走 VPS，则应改成四个更窄的独立规则集，而不是直接使用整个 category-ai-!cn。

第五部分：Android App 包名兜底#

16. 为什么域名规则还不够#

Android 上 ChatGPT App 可能访问：

1
OpenAI 核心域名
2
Sentry
3
Datadog
4
NTP
5
其他共享基础设施

像 sentry.io、gstatic.com 这种是共享服务，不能粗暴地把整个根域都塞进 AI 出口，否则其他 App 也会被误分流。

Mihomo 在 Android 上可以通过 PROCESS-NAME 匹配应用包名，因此可以直接做 App 级兜底。

截至本文整理时，四个官方 Android App 包名为：

1
PROCESS-NAME,com.openai.chatgpt,AI专线
2
PROCESS-NAME,com.anthropic.claude,AI专线
3
PROCESS-NAME,com.google.android.apps.bard,AI专线
4
PROCESS-NAME,ai.x.grok,AI专线

这样：

1
ChatGPT App 发出的辅助请求
2
       ↓
3
仍然跟随 AI 专线

而普通浏览器访问共享 CDN 时，不会因此被全部拖进 AI VPS。

第六部分：一份适合公开分享的 FlClash 覆写脚本#

17. 完整通用版#

Important

这份脚本已经去掉了个人机场节点名、个人订阅域名、真实 IP 和密钥。

使用前至少修改：

MAIN_GROUP_NAME
REPLACE_VPS_IP
REPLACE_UUID
REPLACE_CLIENT_PUBLIC_KEY
REPLACE_SHORT_ID

1
function main(config) {
2
  // ============================================================
3
  // 0. 按自己的机场修改
4
  // ============================================================
5
  const MAIN_GROUP_NAME = "🚀 节点选择";
6

7
  const AI_GROUP_NAME = "AI专线";
8
  const VPS_NODE_NAME = "AI-VPS";
9

10
  const VPS_IP = "REPLACE_VPS_IP";
11

12
  // ============================================================
13
  // 1. 自建 VPS 节点
14
  // ============================================================
15
  const aiVpsProxy = {
16
    name: VPS_NODE_NAME,
17

18
    type: "vless",
19
    server: VPS_IP,
20
    port: 443,
21

22
    uuid: "REPLACE_UUID",
23

24
    network: "tcp",
25
    tls: true,
26
    udp: true,
27

28
    "packet-encoding": "xudp",
29
    flow: "xtls-rprx-vision",
30

31
    servername: "www.bing.com",
32
    "client-fingerprint": "chrome",
33

34
    "reality-opts": {
35
      "public-key": "REPLACE_CLIENT_PUBLIC_KEY",
36
      "short-id": "REPLACE_SHORT_ID"
37
    },
38

39
    smux: {
40
      enabled: false
41
    }
42
  };
43

44
  // ============================================================
45
  // 2. 注入节点，避免重复
46
  // ============================================================
47
  config.proxies = Array.isArray(config.proxies)
48
    ? config.proxies
49
    : [];
50

51
  config.proxies = config.proxies.filter(
52
    (proxy) => proxy && proxy.name !== VPS_NODE_NAME
53
  );
54

55
  config.proxies.push(aiVpsProxy);
56

57
  // ============================================================
58
  // 3. AI 动态规则集
59
  // ============================================================
60
  config["rule-providers"] =
61
    config["rule-providers"] || {};
62

63
  config["rule-providers"]["AI-Global"] = {
64
    type: "http",
65
    behavior: "domain",
66
    format: "mrs",
67

68
    url:
69
      "https://raw.githubusercontent.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/category-ai-!cn.mrs",
70

71
    path:
72
      "./ruleset/ai-global.mrs",
73

74
    interval: 86400,
75

76
    // 规则集下载也通过自建 VPS
77
    proxy: VPS_NODE_NAME
78
  };
79

80
  // ============================================================
81
  // 4. AI 策略组
82
  // ============================================================
83
  config["proxy-groups"] =
84
    Array.isArray(config["proxy-groups"])
85
      ? config["proxy-groups"]
86
      : [];
87

88
  const groups = config["proxy-groups"];
89

90
  const aiGroup = {
91
    name: AI_GROUP_NAME,
92
    type: "select",
93

94
    proxies: [
95
      VPS_NODE_NAME,
96
      MAIN_GROUP_NAME,
97
      "DIRECT"
98
    ]
99
  };
100

101
  const aiGroupIndex = groups.findIndex(
102
    (group) => group && group.name === AI_GROUP_NAME
103
  );
104

105
  if (aiGroupIndex >= 0) {
106
    groups[aiGroupIndex] = aiGroup;
107
  } else {
108
    groups.unshift(aiGroup);
109
  }
110

111
  // ============================================================
112
  // 5. 自建 VPS 也加入机场主选择组，作为手动应急出口
113
  //
114
  // 注意：这里只放进手动 select 组；
115
  // 不要把 VPS 放进 url-test 自动测速组。
116
  // ============================================================
117
  const mainGroup = groups.find(
118
    (group) => group && group.name === MAIN_GROUP_NAME
119
  );
120

121
  if (
122
    mainGroup &&
123
    Array.isArray(mainGroup.proxies)
124
  ) {
125
    mainGroup.proxies =
126
      mainGroup.proxies.filter(
127
        (name) => name !== VPS_NODE_NAME
128
      );
129

130
    mainGroup.proxies.splice(
131
      Math.min(1, mainGroup.proxies.length),
132
      0,
133
      VPS_NODE_NAME
134
    );
135
  }
136

137
  // ============================================================
138
  // 6. Android 四大 AI App 包名兜底
139
  // ============================================================
140
  const androidAiRules = [
141
    "PROCESS-NAME,com.openai.chatgpt,AI专线",
142
    "PROCESS-NAME,com.anthropic.claude,AI专线",
143
    "PROCESS-NAME,com.google.android.apps.bard,AI专线",
144
    "PROCESS-NAME,ai.x.grok,AI专线"
145
  ];
146

147
  // ============================================================
148
  // 7. 公共 AI Rule-Set
149
  // ============================================================
150
  const aiRuleSetRules = [
151
    "RULE-SET,AI-Global,AI专线"
152
  ];
153

154
  // ============================================================
155
  // 8. 最小手工兜底
156
  // ============================================================
157
  const manualAiRules = [
158
    // OpenAI
159
    "DOMAIN-SUFFIX,openai.com,AI专线",
160
    "DOMAIN-SUFFIX,chatgpt.com,AI专线",
161
    "DOMAIN-SUFFIX,oaistatic.com,AI专线",
162
    "DOMAIN-SUFFIX,oaiusercontent.com,AI专线",
163

164
    // Claude
165
    "DOMAIN-SUFFIX,anthropic.com,AI专线",
166
    "DOMAIN-SUFFIX,claude.ai,AI专线",
167
    "DOMAIN-SUFFIX,claude.com,AI专线",
168

169
    // Gemini
170
    "DOMAIN,gemini.google.com,AI专线",
171
    "DOMAIN,aistudio.google.com,AI专线",
172
    "DOMAIN-SUFFIX,gemini.google,AI专线",
173
    "DOMAIN,generativelanguage.googleapis.com,AI专线",
174

175
    // Grok / xAI
176
    "DOMAIN-SUFFIX,grok.com,AI专线",
177
    "DOMAIN-SUFFIX,x.ai,AI专线",
178
    "DOMAIN,grok.x.com,AI专线",
179

180
    // 用于测试出口
181
    "DOMAIN,api.ipify.org,AI专线"
182
  ];
183

184
  // ============================================================
185
  // 9. 防止代理回环
186
  // ============================================================
187
  const safetyRules = [
188
    `IP-CIDR,${VPS_IP}/32,DIRECT,no-resolve`
189
  ];
190

191
  // ============================================================
192
  // 10. 规则优先级
193
  //
194
  // Android App
195
  // ↓
196
  // AI Rule-Set
197
  // ↓
198
  // 手工兜底
199
  // ↓
200
  // 防回环
201
  // ↓
202
  // 机场原规则
203
  // ============================================================
204
  const existingRules =
205
    Array.isArray(config.rules)
206
      ? config.rules
207
      : [];
208

209
  config.rules = [
210
    ...androidAiRules,
211
    ...aiRuleSetRules,
212
    ...manualAiRules,
213
    ...safetyRules,
214
    ...existingRules
215
  ];
216

217
  // ============================================================
218
  // 11. AI 定向 DNS
219
  //
220
  // 不推翻机场原 DNS，只增加 AI 域名策略。
221
  // DNS 查询本身通过 AI-VPS；
222
  // disable-ipv6=true 只丢弃该 DNS 服务器返回的 AAAA。
223
  // ============================================================
224
  config.dns = config.dns || {};
225

226
  config.dns["nameserver-policy"] =
227
    config.dns["nameserver-policy"] || {};
228

229
  config.dns["nameserver-policy"]["rule-set:AI-Global"] = [
230
    "https://1.1.1.1/dns-query#AI-VPS&disable-ipv6=true",
231
    "https://1.0.0.1/dns-query#AI-VPS&disable-ipv6=true"
232
  ];
233

234
  return config;
235
}

展开收起

18. 为什么 AI 规则必须放在 Google / GitHub 等大类规则前#

Mihomo 规则是：

1
从上往下
2
第一条命中就停止

例如 Gemini 使用不少 Google 基础设施。

如果顺序是：

1
Google 大类 → 机场
2
Gemini → AI VPS

某些 Gemini 请求可能在还没轮到 Gemini 规则时，就已经被 Google 大类规则抢走了。

因此应该是：

1
Android AI App
2
↓
3
AI Rule-Set
4
↓
5
AI 手工兜底
6
↓
7
Google / GitHub / YouTube
8
↓
9
机场其他规则

第七部分：DNS 分流#

19. 为什么只给 AI 增加 DNS Policy，而不是重写整个机场 DNS#

DNS 的职责是：

1
域名 → 找到目标 IP

代理规则的职责是：

1
这个连接 → 从哪个出口走

两者不是同一个东西。

本文的策略是：

1
AI 域名
2
  ↓
3
Cloudflare DoH
4
  ↓
5
DNS 请求本身通过 AI-VPS
6

7
其他域名
8
  ↓
9
继续使用机场原 DNS

这样不会为了 AI 分流，把原本已经稳定的整套机场 DNS 全部改掉。

Mihomo 支持：

1
nameserver-policy:
2
  "rule-set:AI-Global":
3
    - "https://1.1.1.1/dns-query#AI-VPS&disable-ipv6=true"

其中：

#AI-VPS：指定 DoH 连接通过该代理；
disable-ipv6=true：丢弃 AAAA 返回；
rule-set:AI-Global：只作用于这组 AI 域名。

Note

这不是“保证不触发 AI 风控”的魔法配置。主要价值是减少解析路径混乱、DNS 污染和不同出口之间不必要的不一致。

第八部分：为什么 `gstatic.com` 不应该整域强制走 AI VPS#

实际观察连接日志时，经常会看到：

1
t0.gstatic.com
2
t1.gstatic.com
3
t2.gstatic.com

走了普通机场。

这不一定是漏流量。

gstatic.com 是 Google 大量产品共用的静态资源/CDN 域。如果写：

1
DOMAIN-SUFFIX,gstatic.com,AI专线

那么 Google Search、Maps、Fonts、登录页甚至一些第三方网页引用的资源，也可能被拖进 AI VPS。

更合理的做法是：

Gemini 明确的 AI 域名 → AI Rule-Set；
Android Gemini App → 包名兜底；
通用 t0/t1/t2.gstatic.com → 保持普通 Google 路径。

判断“漏没漏”的标准不是“看到 Google 域名走机场”，而是看：

1
gemini.google.com
2
generativelanguage.googleapis.com
3
gemini.gstatic.com

这类明确 AI 请求有没有走错。

第九部分：如何验证#

20. 验证 VPS 节点本身#

Windows PowerShell：

Terminal window

1
curl.exe -x http://127.0.0.1:REPLACE_MIXED_PORT `
2
  https://api.ipify.org `
3
  --max-time 20

如果 api.ipify.org 被规则固定到 AI专线，返回值应该是你的 VPS 出口 IP。

21. 验证动态 AI Rule-Set 是否真的加载#

不要只看“预览配置里有 AI-Global”。

找一个没有写在手工兜底里、但属于公共 AI 规则集的网站，例如 Cursor：

Terminal window

1
curl.exe -I `
2
  -x http://127.0.0.1:REPLACE_MIXED_PORT `
3
  https://cursor.com `
4
  --max-time 20

然后打开 FlClash：

1
请求 / Connections

搜索：

1
cursor.com

如果链路显示类似：

1
cursor.com
2
→ AI专线
3
→ AI-VPS

就能说明：

1
AI-Global Rule-Set
2
已经被实际命中

比“文件好像下载了”更有意义。

22. Android 验证 App 包名兜底#

打开 ChatGPT App，发送一条消息后查看 FlClash 请求。

正常情况下，即使看到：

1
sentry.io
2
Datadog
3
NTP
4
其他辅助请求

只要进程/包名显示：

1
com.openai.chatgpt

它也应该命中：

1
AI专线 → AI-VPS

同理可以验证：

1
com.anthropic.claude
2
com.google.android.apps.bard
3
ai.x.grok

第十部分：机场与自建 VPS 怎么配合#

23. 不要把自建 VPS 放进自动测速组#

推荐：

1
机场自动选择
2
├─ 机场节点 A
3
├─ 机场节点 B
4
└─ ...

而：

1
AI-VPS

不要加入 url-test。

否则自动测速可能因为某次抖动，把你的固定 AI 出口切掉。

24. 但可以把 VPS 放进机场主选择组当应急出口#

推荐结构：

1
🚀 节点选择
2
├─ 自动选择
3
├─ AI-VPS       ← 手动应急
4
├─ 节点 A
5
├─ 节点 B
6
└─ ...

正常：

1
普通外网 → 机场
2
AI → AI-VPS

机场整体故障时：

1
手动把主组切到 AI-VPS

普通代理流量也能临时从 VPS 出去。

25. 普通网站走 VPS 会不会“弄脏 IP”#

普通浏览：

1
Google
2
GitHub
3
论坛
4
正常网页
5
少量下载

不会因为经过 VPS 就自动让 IP “变脏”。

真正应该避免的是：

公开代理；
大量陌生人共享；
批量注册；
垃圾邮件；
爬虫/扫描；
BT/P2P；
攻击流量；
大量异常自动化；
长期大带宽下载/视频把 AI 流量挤满。

所以比较合理的定位是：

AI 专用出口 + 全局应急出口

而不是“这台 VPS 只能访问 AI”。

第十一部分：延迟怎么看#

26. 偶尔 800 ms 不代表节点一定坏了#

如果大多数时间：

1
约 200 ms 左右

偶尔某次测速：

1
500 / 800 ms

随后又恢复，通常只是短时抖动。

客户端显示的“延迟”往往不只是 ICMP Ping，还可能包含：

TCP 建连；
TLS / REALITY 握手；
测试 URL；
当时的国际线路拥塞；
本地 Wi-Fi / 蜂窝抖动。

对 AI 长连接来说，更值得关注：

1
持续高延迟
2
频繁 Timeout
3
丢包
4
连接重置
5
长回答中断

而不是单次延迟数字。

第十二部分：常见错误#

27. REALITY 节点测试失败#

先按层排查：

1
1. VPS TCP 443 是否可达
2
2. Xray 是否监听 443
3
3. UUID 是否一致
4
4. PrivateKey / public-key 是否混淆
5
5. short-id 是否一致
6
6. serverName 是否与服务端 serverNames 对应
7
7. REALITY target 从 VPS 是否真的稳定
8
8. 客户端版本是否支持当前字段

查看 Xray：

Terminal window

1
systemctl status xray --no-pager
2
journalctl -u xray -n 100 --no-pager

不要一遇到失败就：

1
重装系统
2
关闭 TLS 校验
3
乱换十几个协议
4
同时开 Mux / WARP / CDN / 多级代理

一次只改一个变量。

28. AI 有些请求仍走机场#

先判断它到底属于：

1
AI 核心请求
2
还是共享基础服务

例如：

1
gstatic.com
2
sentry.io
3
pool.ntp.org

都可能被很多非 AI App 使用。

Android 优先使用：

1
PROCESS-NAME

做 App 级兜底，不要为了一个 App 把整个公共域名全部强制代理。

29. 配置更新后突然不工作#

检查：

1
FlClash 最终预览配置
2
AI-Global provider
3
AI专线策略组选中项
4
机场订阅是否改了主策略组名称
5
Mihomo / FlClash 是否升级
6
公共规则集是否可下载

覆写脚本依赖 MAIN_GROUP_NAME。如果机场把：

1
🚀 节点选择

改了名字，你也要同步改脚本变量。

第十三部分：本文当前还没有做的内容#

这份教程只整理已经跑通的部分。

下面两块将在后续继续：

SSH 密钥登录 + 普通 sudo 用户
验证成功后再考虑关闭 root/password 远程登录
Komari Server 私有面板
Komari Agent
国内三网延迟曲线
最终重启后自动恢复验收
配置备份与恢复演练

Warning

SSH 密钥没有验证成功之前，不要直接关闭 PasswordAuthentication 或 PermitRootLogin，否则可能把自己锁在服务器外面。

第十四部分：参考资料#

30. 官方资料#

31. AI 规则数据#

MetaCubeX/meta-rules-dat
https://github.com/MetaCubeX/meta-rules-dat
category-ai-!cn.mrs 所在分支
https://github.com/MetaCubeX/meta-rules-dat/tree/meta/geo/geosite
v2fly/domain-list-community
https://github.com/v2fly/domain-list-community
v2fly OpenAI 数据
https://github.com/v2fly/domain-list-community/blob/master/data/openai
v2fly Anthropic 数据
https://github.com/v2fly/domain-list-community/blob/master/data/anthropic
v2fly Google DeepMind / Gemini 数据
https://github.com/v2fly/domain-list-community/blob/master/data/google-deepmind
v2fly xAI / Grok 数据
https://github.com/v2fly/domain-list-community/blob/master/data/xai

32. 可作为补充思路的社区项目#

Caution

社区模板适合参考思路，不建议不检查内容就整份复制。

blackmatrix7/ios_rule_script
https://github.com/blackmatrix7/ios_rule_script
Accademia/Additional_Rule_For_Clash
https://github.com/Accademia/Additional_Rule_For_Clash
住宅/AI 分流配置示例：Phlegonlabs/clash-verge-setting
https://github.com/Phlegonlabs/clash-verge-setting

33. Android 官方 App 包名来源#

结语#

最终目标不是堆尽可能多的“网络优化参数”，而是保持结构简单：

1
VPS：
2
Debian
3
└─ Xray
4
   └─ VLESS + REALITY + Vision
5

6
客户端：
7
FlClash / Mihomo
8
├─ Android AI App 包名 → AI 专线
9
├─ category-ai-!cn → AI 专线
10
├─ AI 专线 → 自建 VPS
11
├─ 普通国外流量 → 原机场
12
└─ 国内 / 内网 → DIRECT

出现问题时，也按层定位：

1
VPS 网络
2
→ Xray
3
→ REALITY
4
→ FlClash 节点
5
→ Rule-Set
6
→ DNS
7
→ 单个 App

不要同时修改五六项参数。一次只改变一个变量，再验证结果。

发布前最后自查

搜索整篇文档，确保没有残留：

1
真实 VPS IP
2
真实 SSH 端口
3
UUID
4
PrivateKey
5
public-key
6
short-id
7
VLESS 分享链接
8
机场订阅地址
9
API Key / Cookie / Token

截图也要检查右上角账户名、浏览器书签、订阅 URL、节点 IP、二维码、终端历史命令。

Claude Code Hook 通知与提示音配置

Tue, 04 Aug 2026 00:00:00 GMT

Claude Code Hook 通知与提示音配置#

在 Windows 上，Claude Code 可以通过原生 Hook 在需要权限确认、完成一轮回答或执行失败时显示系统托盘通知，并播放提示音。本次实测的最终方案不依赖第三方通知工具，也不需要更换已有 Hook 配置；只需把 notify.ps1 的播放实现改为同步加载并播放 Windows 自带的 WAV 文件。

最终结论#

保留原有的 %USERPROFILE%\.claude\settings.json Hook 配置，只替换 %USERPROFILE%\.claude\hooks\notify.ps1：

使用 System.Windows.Forms.NotifyIcon 显示托盘气泡通知。
使用 System.Media.SoundPlayer 播放 %WINDIR%\Media 下的 WAV 文件。
播放前显式调用 Load()，再调用 PlaySync()，避免异步播放时脚本过早退出。
Alarm02.wav 或 Alarm03.wav 不存在时，回退到 Alarm01.wav。
声音播放失败时写入脚本目录下的 notify-error.log，不再使用空的 catch 隐藏异常。

事件与声音映射#

Claude Code 事件	Hook 参数	默认声音	用途
`Notification`，匹配 `permission_prompt`	`permission`	`Alarm01.wav`	等待用户批准工具操作
`Stop`	`done`	`Alarm03.wav`	主 Agent 完成本轮响应
`StopFailure`	`error`	`Alarm02.wav`	本轮因 API 或其他错误结束

Stop 表示本轮响应结束，不等同于长期任务的所有工作都已完成；用户主动中断时也不会触发 Stop。StopFailure 用于 API 错误等异常结束场景。

如果当前操作已经被允许、处于自动批准模式，或本身不需要权限，permission_prompt 不会触发；这不是 Hook 失效，完成通知仍可正常触发。

可直接使用的 `notify.ps1`#

文件位置：

1
%USERPROFILE%\.claude\hooks\notify.ps1

Terminal window展开收起

1
param(
2
    [ValidateSet("permission", "done", "error")]
3
    [string]$EventType = "done"
4
)
5

6
$ErrorActionPreference = "Stop"
7

8
Add-Type -AssemblyName System.Windows.Forms
9
Add-Type -AssemblyName System.Drawing
10

11
switch ($EventType) {
12
    "permission" {
13
        $title = "Claude Code 需要确认"
14
        $message = "Claude Code 正在等待你批准操作。"
15
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Warning
16
        $trayIcon = [System.Drawing.SystemIcons]::Warning
17
        $soundPath = "$env:WINDIR\Media\Alarm01.wav"
18
    }
19

20
    "error" {
21
        $title = "Claude Code 执行失败"
22
        $message = "本轮响应因错误而结束。"
23
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Error
24
        $trayIcon = [System.Drawing.SystemIcons]::Error
25
        $soundPath = "$env:WINDIR\Media\Alarm02.wav"
26
    }
27

28
    default {
29
        $title = "Claude Code 已完成"
30
        $message = "本轮回答已经完成，可以回来查看了。"
31
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Info
32
        $trayIcon = [System.Drawing.SystemIcons]::Information
33
        $soundPath = "$env:WINDIR\Media\Alarm03.wav"
34
    }
35
}
36

37
# 某些 Windows 安装没有 Alarm02.wav 或 Alarm03.wav，统一回退到 Alarm01.wav。
38
if (-not (Test-Path -LiteralPath $soundPath)) {
39
    $soundPath = "$env:WINDIR\Media\Alarm01.wav"
40
}
41

42
$notification = $null
43

44
try {
45
    $notification = New-Object System.Windows.Forms.NotifyIcon
46
    $notification.Icon = $trayIcon
47
    $notification.BalloonTipIcon = $tipIcon
48
    $notification.BalloonTipTitle = $title
49
    $notification.BalloonTipText = $message
50
    $notification.Visible = $true
51

52
    $notification.ShowBalloonTip(6000)
53

54
    $player = New-Object System.Media.SoundPlayer $soundPath
55
    $player.Load()
56
    $player.PlaySync()
57

58
    # 保持进程短暂存活，确保气泡通知有时间显示。
59
    Start-Sleep -Seconds 5
60
}
61
catch {
62
    $logPath = Join-Path $PSScriptRoot "notify-error.log"
63

64
    "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')`r`n$($_ | Out-String)" |
65
        Add-Content -Path $logPath -Encoding UTF8
66
}
67
finally {
68
    if ($null -ne $notification) {
69
        $notification.Dispose()
70
    }
71
}

展开收起

Hook 配置#

已经有可用 Hook 时#

不需要修改 settings.json。只要现有命令已经调用 notify.ps1，并把三种事件分别传入 permission、done、error 即可。保留：

1
"shell": "powershell",
2
"async": true

其中 async: true 可以避免通知脚本等待声音播放时阻塞 Claude Code。

在 Windows 上，shell: "powershell" 由 Claude Code 负责选择 PowerShell 运行时，并在 PowerShell 7 不可用时回退到 Windows PowerShell 5.1。除非兼容性测试证明有必要，否则不需要在每个 Hook 命令中硬编码 powershell.exe 的完整路径。

从零配置时的最小示例#

如果尚未配置 Hook，可将下面内容合并进 %USERPROFILE%\.claude\settings.json 的顶层 hooks 对象。已有 env、插件或其他配置时，只添加对应事件，不要覆盖整个文件。

1
{
2
  "hooks": {
3
    "Notification": [
4
      {
5
        "matcher": "permission_prompt",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "shell": "powershell",
10
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType permission",
11
            "async": true
12
          }
13
        ]
14
      }
15
    ],
16
    "Stop": [
17
      {
18
        "hooks": [
19
          {
20
            "type": "command",
21
            "shell": "powershell",
22
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType done",
23
            "async": true
24
          }
25
        ]
26
      }
27
    ],
28
    "StopFailure": [
29
      {
30
        "hooks": [
31
          {
32
            "type": "command",
33
            "shell": "powershell",
34
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType error",
35
            "async": true
36
          }
37
        ]
38
      }
39
    ]
40
  }
41
}

展开收起

安装与验证#

先备份当前可用脚本，再覆盖内容：

Terminal window

1
Copy-Item `
2
  "$env:USERPROFILE\.claude\hooks\notify.ps1" `
3
  "$env:USERPROFILE\.claude\hooks\notify-working.ps1"

依次手动测试三种事件：

Terminal window

1
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType permission
2
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType done
3
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType error

检查 WAV 文件是否存在：

Terminal window

1
Test-Path "$env:WINDIR\Media\Alarm01.wav"
2
Get-ChildItem "$env:WINDIR\Media" -Filter "*.wav" |
3
    Select-Object -ExpandProperty FullName

检查 settings.json 是否仍是合法 JSON：

Terminal window

1
Get-Content "$env:USERPROFILE\.claude\settings.json" -Raw |
2
    ConvertFrom-Json |
3
    Out-Null
4

5
Write-Host "settings.json 格式正确"

完全退出并重新启动 Claude Code，然后运行 /hooks 检查 Notification、Stop 和 StopFailure 是否已注册。

无声音时的排查顺序#

先用默认播放器确认 Windows 音频输出设备、主音量和 WAV 文件本身正常。

再单独测试同步播放：

Terminal window

1
$player = New-Object System.Media.SoundPlayer "$env:WINDIR\Media\Alarm01.wav"
2
$player.Load()
3
$player.PlaySync()

如果当前 PowerShell 版本测试仍无声，可只用 Windows PowerShell 5.1 做兼容性验证，不必先修改 Hook：

Terminal window

1
& "$env:WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" `
2
  -NoProfile `
3
  -Command '$p = New-Object System.Media.SoundPlayer "$env:WINDIR\Media\Alarm01.wav"; $p.Load(); $p.PlaySync()'

若直接播放成功但 Hook 无声，查看脚本目录下的 notify-error.log，并确认 Claude Code 使用的 Hook 命令确实指向当前 notify.ps1。
检查 Windows 音量混合器中的系统声音、PowerShell 或终端应用是否被单独静音，或输出到了错误设备。

如果提示禁止运行脚本，只对当前用户启用本地脚本即可：

Terminal window

1
Set-ExecutionPolicy `
2
  -Scope CurrentUser `
3
  -ExecutionPolicy RemoteSigned

不需要为了运行这个本地脚本而使用 ExecutionPolicy Bypass。

本次排障中不需要保留的方案#

不需要安装 Code-Notify 或其他第三方通知模块。
不需要把 WAV 文件关联到默认播放器作为 Hook 的播放机制。
不需要使用 Windows Media Player COM 组件或 winmm.dll 的替代实现。
不要为了绕过安全软件而信任远程下载后立即执行的 PowerShell 安装脚本。

本方案依赖 Windows 自带的 Forms、Drawing 和 SoundPlayer，不产生网络请求，也不需要提交本机的 .claude 配置、日志或声音文件。

参考#

Claude Code Hooks 官方文档

GitHub 提交邮箱隐私与 Git 多身份配置

Mon, 27 Jul 2026 00:00:00 GMT

GitHub 提交邮箱隐私与 Git 多身份配置#

目标#

实现以下效果：

GitHub 提交记录不公开真实邮箱。
默认使用 GitHub 身份提交。
公司项目目录自动切换为公司身份。
避免每次进入仓库后手动修改 user.name 和 user.email。
阻止命令行推送意外暴露真实邮箱。

本文全部使用占位符，不包含真实姓名、邮箱、用户名或本机目录。

一、GitHub 需要开启的两个邮箱隐私设置#

进入：

1
GitHub 头像 → Settings → Emails

开启以下两个选项。

1. Keep my email addresses private#

作用：

隐藏 GitHub 网页端提交使用的真实邮箱。
使用 GitHub 提供的 noreply 邮箱。
降低真实邮箱出现在公开提交记录中的风险。

GitHub 提供的匿名邮箱通常类似：

1
<ACCOUNT_ID>+<GITHUB_USERNAME>@users.noreply.github.com

请从 GitHub 的 Settings → Emails 页面复制自己的实际地址，不要手动猜测。

2. Block command line pushes that expose my email#

作用：

当命令行提交使用了受保护的真实邮箱时阻止推送。
防止新电脑、旧仓库或错误配置意外暴露邮箱。
作为 Git 本地配置之外的第二层保护。

这两个设置属于 GitHub 账户的邮箱隐私设置，不是仓库的 Secret scanning 或 Push protection。

二、与仓库安全扫描功能的区别#

邮箱隐私设置#

位置：

1
GitHub Settings → Emails

主要保护：

Commit 作者邮箱
GitHub 账户真实邮箱
命令行推送时的邮箱隐私

Secret scanning#

主要扫描：

API Key
Access Token
云服务密钥
数据库凭证
私钥及其他敏感凭证

Push protection#

主要作用：

在敏感凭证进入仓库前阻止推送。
保护的是代码中的密钥，不是 Commit 作者邮箱。

三、设置默认 GitHub 提交身份#

默认身份用于：

个人项目
开源项目
知识库
非公司目录下的其他 Git 仓库

执行：

Terminal window

1
git config --global user.name "<GITHUB_USERNAME>"
2
git config --global user.email "<GITHUB_NOREPLY_EMAIL>"

示例占位形式：

Terminal window

1
git config --global user.name "<GITHUB_USERNAME>"
2
git config --global user.email "<ACCOUNT_ID>+<GITHUB_USERNAME>@users.noreply.github.com"

检查：

Terminal window

1
git config --global user.name
2
git config --global user.email

四、创建公司专用 Git 配置#

在用户主目录创建：

1
~/.gitconfig-company

Windows PowerShell 可使用：

Terminal window

1
notepad $HOME\.gitconfig-company

内容：

1
[user]
2
    name = <COMPANY_GIT_NAME>
3
    email = <COMPANY_GIT_EMAIL>

该文件只保存公司提交身份。

五、按目录自动切换身份#

打开全局 Git 配置：

Terminal window

1
git config --global --edit

添加：

1
[user]
2
    name = <GITHUB_USERNAME>
3
    email = <GITHUB_NOREPLY_EMAIL>
4

5
[includeIf "gitdir/i:<COMPANY_GIT_ROOT>/"]
6
    path = ~/.gitconfig-company

Windows 路径示例使用占位符：

1
[includeIf "gitdir/i:D:/<COMPANY_PROJECTS>/"]
2
    path = ~/.gitconfig-company

配置逻辑：

默认使用 GitHub 身份。
仓库位于公司项目根目录下时，自动加载公司身份。
gitdir/i 表示路径匹配时忽略大小写。
路径结尾建议保留 /。
Git 配置中建议使用 /，不要使用 Windows 反斜杠 \。

六、推荐目录结构#

1
D:/Git/Company/
2
D:/Git/Personal/
3
D:/Git/OpenSource/

对应配置：

1
[user]
2
    name = <GITHUB_USERNAME>
3
    email = <GITHUB_NOREPLY_EMAIL>
4

5
[includeIf "gitdir/i:D:/Git/Company/"]
6
    path = ~/.gitconfig-company

最终效果：

仓库位置	自动使用的身份
`D:/Git/Company/`	公司姓名与公司邮箱
`D:/Git/Personal/`	GitHub 用户名与 noreply 邮箱
`D:/Git/OpenSource/`	GitHub 用户名与 noreply 邮箱

七、检查当前仓库使用的身份#

进入任意 Git 仓库后执行：

Terminal window

1
git config --get user.name
2
git config --get user.email

查看配置来源：

Terminal window

1
git config --show-origin --get user.name
2
git config --show-origin --get user.email

一次查看身份配置及来源：

Terminal window

1
git config --show-origin --get-regexp "^user\.(name|email)$"

查看 Git 实际准备使用的作者与提交者身份：

Terminal window

1
git var GIT_AUTHOR_IDENT
2
git var GIT_COMMITTER_IDENT

八、仓库级配置可能覆盖自动配置#

Git 配置通常按照以下优先级生效：

1
系统级配置
2
< 全局配置
3
< includeIf 加载的配置
4
< 当前仓库本地配置

检查当前仓库是否存在本地身份配置：

Terminal window

1
git config --local --get user.name
2
git config --local --get user.email

如需删除本地覆盖：

Terminal window

1
git config --local --unset user.name
2
git config --local --unset user.email

删除后重新检查：

Terminal window

1
git config --get user.name
2
git config --get user.email

九、检查最近提交使用的邮箱#

查看最近一次提交：

Terminal window

1
git log -1 --format="作者：%an <%ae>%n提交者：%cn <%ce>"

查看最近 10 次提交：

Terminal window

1
git log -10 --format="%h | %an <%ae> | %s"

PowerShell 中查看历史中出现过的全部邮箱：

Terminal window

1
git log --format="%ae" | Sort-Object -Unique

十、错误邮箱尚未推送时的处理#

如果已经 Commit，但尚未 Push：

先确认当前身份配置正确：

Terminal window

1
git config user.name
2
git config user.email

重写最后一次提交的作者信息：

Terminal window

1
git commit --amend --reset-author --no-edit

再次检查：

Terminal window

1
git log -1 --format="作者：%an <%ae>%n提交者：%cn <%ce>"

十一、错误邮箱已经推送时的说明#

修改 Git 配置只影响之后创建的 Commit。

已经推送的提交：

不会自动改成新邮箱。
旧邮箱仍可能保留在 Git 历史中。
修改历史通常需要重写 Commit 并强制推送。
多人协作仓库不建议随意重写历史。

个人仓库确实需要清理时，可使用：

1
git filter-repo

在操作前应先备份仓库。

十二、GitHub 如何关联提交到账号#

GitHub 通常根据 Commit 邮箱判断提交属于哪个账号。

要让提交正确关联到 GitHub 账号，邮箱应满足以下任一条件：

使用 GitHub 账户中已验证的邮箱。
使用 GitHub 提供的 noreply 邮箱。

隐私优先时推荐：

1
<ACCOUNT_ID>+<GITHUB_USERNAME>@users.noreply.github.com

十三、可选：PowerShell 身份检查函数#

将下面内容加入 PowerShell 配置文件：

Terminal window

1
function git-whoami {
2
    Write-Host "仓库目录：" (Get-Location)
3
    Write-Host "Git 用户名：" (git config user.name)
4
    Write-Host "Git 邮箱：" (git config user.email)
5
    Write-Host ""
6
    Write-Host "配置来源："
7
    git config --show-origin --get-regexp "^user\.(name|email)$"
8
}

进入仓库后执行：

Terminal window

1
git-whoami

即可查看当前提交身份。

十四、配置检查清单#

已开启 Keep my email addresses private
已开启 Block command line pushes that expose my email
已从 GitHub 页面复制正确的 noreply 邮箱
已设置默认 GitHub 用户名
已设置默认 GitHub noreply 邮箱
已创建 ~/.gitconfig-company
已添加按目录匹配的 includeIf
公司目录路径末尾保留 /
已在个人仓库检查身份
已在公司仓库检查身份
已检查仓库级配置是否覆盖全局配置
已检查最近一次 Commit 的作者邮箱

核心配置模板#

全局配置：

1
[user]
2
    name = <GITHUB_USERNAME>
3
    email = <GITHUB_NOREPLY_EMAIL>
4

5
[includeIf "gitdir/i:<COMPANY_GIT_ROOT>/"]
6
    path = ~/.gitconfig-company

公司身份配置：

1
[user]
2
    name = <COMPANY_GIT_NAME>
3
    email = <COMPANY_GIT_EMAIL>

最终策略：

1
默认目录：GitHub 用户名 + GitHub noreply 邮箱
2
公司目录：公司提交姓名 + 公司邮箱

为 Linux.do 指定固定 DNS 与直连规则

Wed, 22 Jul 2026 00:00:00 GMT

为 Linux.do 指定固定 DNS 与直连规则#

目标#

让访问 linux.do 时：

固定使用指定的 DoH DNS 解析；
网站流量使用 DIRECT 直连；
机场节点失效时，只要 Clash/Mihomo 内核仍在运行，Linux.do 仍可尝试正常访问；
分别适配 Clash Verge Rev 和 FlClash；
能够通过“请求/连接”页面验证规则是否真正命中。

Important

DNS 只负责把域名解析为 IP，并不能保证网站一定能够直连。

这套方案只能处理：

1
机场节点失效
2
+
3
Clash/Mihomo 内核仍在运行

如果代理客户端完全退出、内核停止，客户端内部的 DNS 和规则都会失效。

一、整体原理#

访问链路：

1
浏览器或应用
2
  ↓
3
Clash Verge Rev / FlClash
4
  ↓
5
Mihomo 匹配 linux.do
6
  ├─ DNS：指定 DoH
7
  └─ 出站：DIRECT

需要同时配置两部分：

1
nameserver-policy

负责指定 DNS。

1
DOMAIN-SUFFIX,linux.do,DIRECT

负责指定网站流量直连。

只配置 DNS、不配置 DIRECT，可能出现：

1
域名使用了指定 DNS
2
但网站流量仍然走代理节点

只配置 DIRECT、不配置 DNS，可能出现：

1
网站已直连
2
但仍使用默认 DNS，解析结果可能不理想

二、核心配置含义#

1. 域名匹配#

1
"+.linux.do"

匹配：

1
linux.do
2
www.linux.do
3
api.linux.do
4
其他多级子域名

2. 直连规则#

1
DOMAIN-SUFFIX,linux.do,DIRECT

表示：

1
linux.do 及其所有子域名
2
→ 使用 DIRECT
3
→ 不经过机场代理节点

3. DNS 地址后的 `#DIRECT`#

1
https://你的DNS地址/dns-query#DIRECT

表示连接这个 DoH 服务器本身时也使用直连，不依赖代理节点。

Warning

前提是该 DoH 地址从当前网络可以直接访问。

如果该 DNS 本身必须通过代理才能访问，就不要添加 #DIRECT，或者更换为可直连的 DNS。

三、Clash Verge Rev 配置#

1. 找到 Merge 配置#

新版 Clash Verge Rev 中，Merge 配置显示为：

1
全局扩展覆写配置

路径：

1
Clash Verge Rev
2
→ 订阅
3
→ 全局扩展覆写配置

右上角通常会显示：

1
Merge

不要直接编辑机场订阅原文件，否则订阅更新后可能覆盖修改。

2. Linux.do 固定 DNS + 直连#

编辑“全局扩展覆写配置”：

1
# Clash Verge Rev：Linux.do 固定 DNS + 直连
2

3
profile:
4
  store-selected: true
5

6
prepend-rules:
7
  - DOMAIN-SUFFIX,linux.do,DIRECT
8

9
dns:
10
  enable: true
11
  nameserver-policy:
12
    "+.linux.do":
13
      - "https://你的DNS地址/dns-query#DIRECT"

将：

1
https://你的DNS地址/dns-query

替换为真实的 DoH 地址。

示例：

1
profile:
2
  store-selected: true
3

4
prepend-rules:
5
  - DOMAIN-SUFFIX,linux.do,DIRECT
6

7
dns:
8
  enable: true
9
  nameserver-policy:
10
    "+.linux.do":
11
      - "https://cloudflare-dns.com/dns-query#DIRECT"

3. 配置多个 DNS#

1
profile:
2
  store-selected: true
3

4
prepend-rules:
5
  - DOMAIN-SUFFIX,linux.do,DIRECT
6

7
dns:
8
  enable: true
9
  nameserver-policy:
10
    "+.linux.do":
11
      - "https://你的专用DNS1/dns-query#DIRECT"
12
      - "https://你的专用DNS2/dns-query#DIRECT"
13
      - "https://cloudflare-dns.com/dns-query#DIRECT"

建议配置 2～3 个即可。

Note

多个 DNS 不应理解为严格的主备顺序。

更适合把它理解为给 Mihomo 提供多个可用解析器，提高整体可用性。

4. 已有 `dns:` 时的处理#

YAML 中不能重复两个同级 dns:。

错误：

1
dns:
2
  ipv6: false
3

4
dns:
5
  enable: true

正确：

1
dns:
2
  ipv6: false
3
  enable: true
4
  nameserver-policy:
5
    "+.linux.do":
6
      - "https://你的DNS地址/dns-query#DIRECT"

5. 保存和生效#

保存后：

刷新机场订阅；
必要时重启 Mihomo 内核；
重启浏览器；
打开 Linux.do 测试。

Windows 可以清理 DNS 缓存：

Terminal window

1
ipconfig /flushdns

四、FlClash 图形界面配置#

FlClash 可以不写 YAML，分别配置：

1
DNS 覆写
2
+
3
附加规则

1. 打开 DNS 覆写#

路径通常为：

1
FlClash
2
→ 工具
3
→ 覆写
4
→ 进阶配置
5
→ DNS

推荐设置：

1
覆写 DNS：开启
2
状态：开启
3
IPv6：关闭
4
遵守规则：关闭
5
PreferH3：关闭
6
DNS 模式：fakeip

说明：

覆写 DNS：用 FlClash 的 DNS 设置覆盖订阅中的 DNS；
状态：关闭后会退回系统 DNS；
遵守规则：当前场景建议关闭，避免 DNS 查询跟随代理规则；
PreferH3：不是必须，可以保持关闭；
fakeip：可以继续使用，不影响本教程。

2. 配置域名服务器策略#

进入：

1
DNS
2
→ 域名服务器策略
3
→ 添加

填写：

1
键：
2
+.linux.do
3

4
值：
5
https://你的DNS地址/dns-query#DIRECT

最终应显示类似：

1
+.linux.do
2
https://你的DNS地址/dns-query#DIRECT

这部分等价于：

1
dns:
2
  enable: true
3
  nameserver-policy:
4
    "+.linux.do": "https://你的DNS地址/dns-query#DIRECT"

3. 删除默认示例策略#

FlClash 的域名服务器策略中可能默认出现：

1
www.baidu.com
2
114.114.114.114
3

4
+.internal.crop.com
5
10.0.0.1
6

7
geosite:cn
8
https://doh.pub/dns-query

如果只想让 Linux.do 使用指定 DNS，建议删除这些示例，只保留：

1
+.linux.do
2
https://你的DNS地址/dns-query#DIRECT

其中：

1
geosite:cn

会影响大量中国大陆域名，而不只是 Linux.do。

4. 添加 Linux.do 直连规则#

路径：

1
FlClash
2
→ 工具
3
→ 覆写
4
→ 进阶配置
5
→ 附加规则
6
→ 添加

填写：

1
规则类型：DOMAIN-SUFFIX
2
内容：linux.do
3
规则目标：DIRECT

保存后的卡片应类似：

1
DOMAIN_SUFFIX                 DIRECT
2
linux.do

最终等价于：

1
DOMAIN-SUFFIX,linux.do,DIRECT

5. 常见填写错误#

错误填写：

1
规则类型：DOMAIN-SUFFIX
2
内容：DOMAIN-SUFFIX
3
规则目标：DIRECT

这相当于：

1
DOMAIN-SUFFIX,DOMAIN-SUFFIX,DIRECT

不会匹配 Linux.do。

正确填写：

1
规则类型：DOMAIN-SUFFIX
2
内容：linux.do
3
规则目标：DIRECT

6. 为什么没有“不解析 IP”和“匹配来源 IP”#

这是正常现象。

DOMAIN-SUFFIX 是域名规则，不需要这些参数。

FlClash 只会在部分 IP 类规则中显示附加参数，例如：

1
GEOIP
2
IP-CIDR
3
IP-CIDR6
4
IP-ASN
5
RULE-SET

所以对 Linux.do 的域名后缀规则，只需填写：

1
DOMAIN-SUFFIX
2
linux.do
3
DIRECT

没有以下选项并不代表配置不完整：

1
不解析 IP
2
匹配来源 IP

7. FlClash 图形界面的多个 DNS 限制#

FlClash 的“域名服务器策略”图形界面通常是一组：

1
键 → 单个值

因此一个域名在图形界面里通常只能直接对应一个 DNS 字符串。

推荐先这样配置：

1
+.linux.do
2
→ https://你的主要DNS/dns-query#DIRECT

如果必须给 Linux.do 配置多个 DNS，可以改用 FlClash 的覆写脚本。

五、FlClash 多 DNS 覆写脚本#

路径：

1
FlClash
2
→ 工具
3
→ 覆写
4
→ 进阶配置
5
→ 脚本
6
→ 添加

脚本：

1
const main = (config) => {
2
  if (!config.dns) {
3
    config.dns = {};
4
  }
5

6
  config.dns.enable = true;
7
  config.dns["respect-rules"] = false;
8

9
  if (!config.dns["nameserver-policy"]) {
10
    config.dns["nameserver-policy"] = {};
11
  }
12

13
  config.dns["nameserver-policy"]["+.linux.do"] = [
14
    "https://你的专用DNS1/dns-query#DIRECT",
15
    "https://你的专用DNS2/dns-query#DIRECT"
16
  ];
17

18
  if (!Array.isArray(config.rules)) {
19
    config.rules = [];
20
  }
21

22
  config.rules = config.rules.filter(
23
    (rule) => rule !== "DOMAIN-SUFFIX,linux.do,DIRECT"
24
  );
25

26
  config.rules.unshift("DOMAIN-SUFFIX,linux.do,DIRECT");
27

28
  return config;
29
};

展开收起

保存后，把当前订阅的覆写模式切换为：

1
脚本

并选择刚创建的脚本。

Warning

使用脚本方案时，建议关闭 FlClash 图形界面的“覆写 DNS”，避免图形 DNS 配置再次覆盖脚本结果。

六、浏览器和 ZeroOmega 注意事项#

如果 Chrome 使用 ZeroOmega / Proxy SwitchyOmega：

不要在 ZeroOmega 中直接把 linux.do 设置为浏览器级 DIRECT，否则请求可能绕过 Clash，Mihomo 的 DNS 策略无法参与。

正确链路：

1
Chrome
2
→ ZeroOmega
3
→ Clash Verge Rev 本地代理端口
4
→ Clash 内部匹配 linux.do
5
→ DNS 使用指定 DoH
6
→ 网站连接使用 DIRECT

也就是说：

1
浏览器把流量交给 Clash
2
Clash 再决定 DIRECT

七、验证配置是否真正生效#

1. 检查请求或连接#

访问：

1
https://linux.do

在 Clash Verge Rev 或 FlClash 中打开：

1
请求
2
或
3
连接

正确结果应包含：

1
目标域名：linux.do
2
规则：DOMAIN-SUFFIX
3
代理链：DIRECT

如果显示：

1
节点选择
2
→ 某个代理节点

说明 DNS 可能已经生效，但 DIRECT 规则没有真正命中。

2. FlClash 显示代理节点时的完整排查#

第一步：检查出站模式#

进入：

1
FlClash
2
→ 仪表盘
3
→ 出站模式

必须选择：

1
规则

不能是：

1
全局

如果处于“全局”模式，所有请求都会走当前选择的代理节点，附加的域名规则不会按预期生效。

第二步：检查当前订阅的覆写模式#

进入：

1
FlClash
2
→ 配置
3
→ 点击当前正在使用的订阅
4
→ 覆写

确认覆写模式是：

1
标准

因为通过图形界面添加的“附加规则”属于标准覆写模式。

如果当前使用的是：

1
脚本
2
或
3
自定义

标准模式中的附加规则可能不会进入最终配置。

第三步：确认当前订阅启用了全局附加规则#

在当前订阅的标准覆写页面中找到：

1
控制全局附加规则

确认：

1
DOMAIN-SUFFIX,linux.do,DIRECT

处于启用状态。

需要注意：

1
工具 → 附加规则

中能够看到规则，只代表规则已经创建。

当前订阅仍有可能单独禁用了这条全局附加规则。

第四步：使用“预览”检查最终配置#

进入当前订阅的覆写页面，点击：

1
预览

搜索：

1
linux.do

最终配置中必须存在：

1
rules:
2
  - DOMAIN-SUFFIX,linux.do,DIRECT

并且它必须位于最终兜底规则之前，例如：

1
- MATCH,节点选择

正确顺序：

1
rules:
2
  - DOMAIN-SUFFIX,linux.do,DIRECT
3

4
  # 机场其他规则……
5

6
  - MATCH,节点选择

如果 linux.do 规则位于 MATCH 之后，它永远不会命中。

如果预览中完全找不到该规则，说明当前订阅没有应用这条附加规则。

第五步：关闭旧连接#

规则修改不会自动改变已经建立的 TCP 连接。

建议执行：

1
关闭 Chrome
2
→ 在 FlClash 的连接页面关闭现有连接
3
→ 停止 FlClash
4
→ 重新启动 FlClash
5
→ 确认出站模式为“规则”
6
→ 重新打开 Chrome
7
→ 再访问 Linux.do

如果不关闭旧连接，界面中可能仍显示之前使用的代理节点。

3. 模拟节点失效#

可以切换到不可用节点，然后重新访问 Linux.do。

预期：

1
代理节点不可用
2
+
3
Mihomo 内核仍运行
4
+
5
linux.do 命中 DIRECT
6
+
7
指定 DoH 可直连
8
=
9
Linux.do 仍可尝试打开

4. 客户端完全退出时#

如果 Clash Verge Rev 或 FlClash 整体退出：

1
nameserver-policy 不再工作
2
DIRECT 规则不再工作
3
本地代理端口也可能停止监听

因此网站可能仍打不开。

要实现客户端退出后仍可访问，需要换成系统级方案，例如：

1
Windows 全局 DNS
2
hosts 文件
3
AdGuard Home
4
MosDNS
5
dnscrypt-proxy

八、最终配置速查#

Clash Verge Rev#

1
profile:
2
  store-selected: true
3

4
prepend-rules:
5
  - DOMAIN-SUFFIX,linux.do,DIRECT
6

7
dns:
8
  enable: true
9
  nameserver-policy:
10
    "+.linux.do":
11
      - "https://你的DNS地址/dns-query#DIRECT"

FlClash#

DNS：

1
覆写 DNS：开启
2
状态：开启
3
遵守规则：关闭
4

5
域名服务器策略：
6
+.linux.do
7
→ https://你的DNS地址/dns-query#DIRECT

附加规则：

1
规则类型：DOMAIN-SUFFIX
2
内容：linux.do
3
规则目标：DIRECT

运行条件：

1
出站模式：规则
2
当前订阅覆写模式：标准
3
当前订阅已启用该全局附加规则

九、故障排查速查表#

Linux.do 仍然走代理#

依次检查：

1
1. 出站模式是否为“规则”
2
2. 当前订阅覆写模式是否为“标准”
3
3. 当前订阅是否启用了这条全局附加规则
4
4. 预览中是否存在 DOMAIN-SUFFIX,linux.do,DIRECT
5
5. 该规则是否位于 MATCH 之前
6
6. 是否关闭了修改前建立的旧连接

DNS 已配置但网站仍打不开#

检查：

DoH 地址是否真实有效；
DoH 地址是否能直连；
是否误加了无法直连的 #DIRECT；
Linux.do 本身是否可以从当前网络直连；
是否存在 TLS、SNI、路由或网络层限制。

FlClash 中没有“不解析 IP”#

正常。

DOMAIN-SUFFIX 不需要该选项。

配置保存后没有生效#

尝试：

保存覆写配置；
确认当前订阅应用了覆写；
停止并重新启动客户端；
重启 Mihomo 核心；
清理 DNS 缓存；
关闭旧连接；
重新访问 Linux.do；
在“请求/连接”中查看实际命中的规则。

DNS 策略里有很多默认条目#

如果只想处理 Linux.do，删除其他示例，只保留：

1
+.linux.do
2
→ 你的 DoH

AI 编程工具与代理 MOC

Sun, 19 Jul 2026 00:00:00 GMT

AI 编程工具与代理 MOC#

主题导航：下列教程均为公开笔记。公司网络细节不进入本页。

主题说明#

围绕 Windows 上 Codex / Claude 等 AI 工具的软件级代理、DNS 与排障，以及用这些工具做前端 UI 的工作流。

入门#

电脑必备软件 — 公开：基础工具清单
Codex Windows 微软商店安装包提取与手动更新 — 公开：安装与更新
Codex Microsoft Store 更新卡住排查 — 公开：商店更新队列与 DoSvc 排障
Codex 与 Claude Code 规则文件统一 — 公开：共用一份 AGENTS.md

配置#

Codex Claude 软件级代理设置教程 — 公开：Proxifier / 启动脚本优先方案
ChatGPT Windows 升级后 Proxifier 网络异常排查 — 公开：升级后网络与 DNS
用一台美国 VPS 搭建 AI 专用出口：Xray REALITY + FlClash + Mihomo 动态 AI 分流 — 公开：AI 服务固定 VPS 出口与动态分流

问题排查#

公司网络 / VPN / TUN 共存：私有环境笔记（不在此列出文件名），按需在 Vault 内搜索

进阶实践#

AI 前端 UI 设计：从零设计方向到落地工作流 — 公开：没有设计方向时，先研究再写 UI
Obsidian 私人知识库自动发布 Quartz 与 Cloudflare Pages — 公开：知识库发布链路

待补充#

终端-only 代理脚本模板
多机同步代理规则的注意事项

Tampermonkey 多电脑同步指南

Sun, 19 Jul 2026 00:00:00 GMT

Tampermonkey 多电脑同步指南#

结论

Tampermonkey 可以通过 OneDrive、Google Drive、WebDAV 等方式在不同电脑之间同步脚本。

第二台电脑开启同步后，通常不是简单地“云端覆盖本地”，而是进行合并同步；同一脚本发生冲突时，通常以修改时间较新的版本为准。

第一次同步前，应先在两台电脑分别导出 ZIP 备份。

适用场景#

适合以下情况：

公司电脑和个人电脑都安装了 Tampermonkey
两台电脑使用不同浏览器，例如 Chrome 和 Edge
希望同步已安装的油猴脚本
希望同步自己修改或编写的脚本
不希望手动逐个导入脚本

第一台电脑：建立云端基准#

应先选择脚本最完整、配置最正确的一台电脑作为主电脑。

操作步骤#

点击浏览器工具栏中的 Tampermonkey 图标。
打开 管理面板。
进入设置。
将配置模式切换为高级。
找到 脚本同步。
同步类型选择 OneDrive。
登录并授权 Microsoft 账号。
开启脚本同步。
手动执行一次同步。
确认同步状态没有报错。

开启同步前备份#

进入：

Tampermonkey 管理面板 → 实用工具 → 导出 ZIP

建议导出：

已安装脚本
脚本源代码
脚本相关设置
脚本存储数据（如果导出界面提供该选项）

备份文件建议命名：

1
tampermonkey-main-2026-07-19.zip

第二台电脑开启同步会发生什么#

第二台电脑开启同步时，通常会将：

云端已有脚本
第二台电脑本地已有脚本

进行合并处理，而不是直接把第二台电脑全部清空。

情况一：本地存在云端没有的脚本#

通常会：

保留本地脚本
将本地脚本上传到同步空间
出现在其他已同步设备上

但第一次同步前仍然建议备份，以防版本或删除记录产生冲突。

情况二：云端存在、本地不存在#

通常会：

将云端脚本下载到第二台电脑
自动出现在 Tampermonkey 管理面板中

情况三：两边存在同一个脚本，代码不同#

这是风险最高的情况。

Tampermonkey 通常会根据脚本标识和修改时间判断版本，修改时间较新的版本可能覆盖较旧版本。

同一脚本一般通过以下信息识别：

1
// @name
2
// @namespace

也可能结合脚本内部 ID 或同步记录判断。

典型风险

第一台电脑上的脚本代码是正确版本，但第二台电脑上的同名脚本修改时间更晚。

第二台电脑开启同步后，较新的本地版本可能上传到云端，并进一步覆盖第一台电脑上的正确版本。

第二台电脑的安全操作顺序#

1. 先备份第二台电脑#

进入：

Tampermonkey 管理面板 → 实用工具 → 导出 ZIP

建议命名：

1
tampermonkey-second-pc-before-sync-2026-07-19.zip

2. 检查是否存在同名脚本#

重点检查：

@name 相同
@namespace 相同
自己手动修改过的脚本
自己编写但没有发布地址的脚本
公司电脑和个人电脑分别修改过的脚本

3. 暂停脚本修改#

第一次同步期间：

不要同时在两台电脑修改同一个脚本
不要同时删除同一个脚本
不要同时执行脚本更新
不要频繁开启和关闭同步

4. 第二台电脑开启 OneDrive 同步#

使用和第一台电脑相同的 Microsoft 账号。

5. 同步后立即检查#

重点检查：

脚本数量是否正常
重要脚本是否存在
脚本启用状态是否正确
自定义修改是否保留
是否出现重复脚本
是否有脚本被意外降级
是否有脚本变成旧版本

哪些内容通常可以同步#

Tampermonkey 的脚本同步通常主要处理：

已安装脚本列表
脚本源代码
脚本新增、修改和删除记录
脚本启用或禁用状态
部分脚本元数据
部分脚本设置

哪些内容不一定同步#

不要把脚本同步理解成整套浏览器环境同步。

以下内容通常不会完整同步，或者需要脚本本身支持：

网站登录状态
Cookie
网站 localStorage
IndexedDB
浏览器缓存
浏览器扩展权限
网站弹窗授权
下载目录权限
跨域访问授权
脚本使用的账号密码
API Key
Token
Base URL
黑名单和白名单
脚本自定义界面中的参数

`GM_setValue` 数据#

很多脚本通过以下 API 保存自己的运行数据：

1
GM_setValue("key", value);
2
GM_getValue("key");

这些数据通常属于当前浏览器中的脚本存储，不应默认认为会随脚本代码一起同步。

因此可能出现：

脚本代码已经同步成功
第二台电脑也已经安装脚本
但脚本内部配置仍然为空
需要重新填写 API Key、规则或账号

判断方法

如果脚本提供“导出配置”“导入配置”“云同步”功能，应优先使用脚本自身的配置导出或同步功能。

Tampermonkey 负责同步脚本，脚本自己的数据最好由脚本自身负责。

冲突处理#

发现脚本被错误覆盖时：

立即暂停两台电脑的 Tampermonkey 同步。
不要继续修改被覆盖的脚本。
从之前导出的 ZIP 中恢复脚本。
或从 GitHub 私有仓库恢复正确版本。
删除云端错误版本前，再次确认备份存在。
只在一台电脑上修改并保存正确版本。
确认修改时间更新后，再重新开启同步。
等第一台电脑上传完成后，再开启第二台电脑。

最稳妥的首次迁移流程#

否

是

选择脚本最完整的主电脑

主电脑导出 ZIP

主电脑开启 OneDrive 同步

确认云端同步完成

第二台电脑导出 ZIP

检查同名和手动修改脚本

第二台电脑开启同步

检查脚本数量与重要脚本

是否出现冲突

完成首次同步

暂停同步并从 ZIP 或 Git 恢复

否

是

选择脚本最完整的主电脑

主电脑导出 ZIP

主电脑开启 OneDrive 同步

确认云端同步完成

第二台电脑导出 ZIP

检查同名和手动修改脚本

第二台电脑开启同步

检查脚本数量与重要脚本

是否出现冲突

完成首次同步

暂停同步并从 ZIP 或 Git 恢复

检查清单#

首次同步前#

已确定哪台电脑是主电脑
主电脑已经导出 ZIP
第二台电脑已经导出 ZIP
已检查两台电脑是否有同名脚本
已检查是否有自己手动修改的脚本
已记录重要脚本中的 API Key 和配置
第一次同步期间不会同时修改脚本

同步后#

脚本数量正确
重要脚本仍然存在
自定义代码没有被覆盖
启用状态正确
没有出现重复脚本
脚本内部配置仍然可用
API Key 和 Token 没有丢失
网站权限已经重新授权

DNSHE 免费域名注册与 Cloudflare 托管教程

Sun, 19 Jul 2026 00:00:00 GMT

DNSHE 免费域名注册与 Cloudflare 托管教程#

文档说明

本文用于记录如何在 DNSHE 注册免费域名，并将域名托管到 Cloudflare。

推荐用途：

Obsidian + Quartz 知识库
Cloudflare Pages
Oracle VPS
CPA / New API 测试服务
API、Webhook、个人 Demo

不建议用于：

主邮箱域名
银行、支付、密码管理器
重要账号的唯一回调域名
无法迁移的正式商业项目

一、先理解这种免费域名是什么#

DNSHE 提供的并不是你直接向注册局持有的 .com、.net 独立域名，而是类似下面这样的可独立管理子域名：

1
yourname.de5.net
2
yyq.us.ci
3
yyq.cc.cd

虽然它们可以作为独立区域加入 Cloudflare，但上级根域仍由 DNSHE 或根域持有人控制。

重要风险

这种域名适合测试和个人项目，但不属于可以自由转移注册商的长期数字资产。

DNSHE、上级根域持有人或服务规则发生变化时，域名可能受到影响。

二、后缀选择建议#

优先选择已经进入 Public Suffix List、可作为独立区域加入 Cloudflare 的后缀。

后缀	建议程度	说明
`de5.net`	⭐⭐⭐⭐⭐	当前最推荐，适合技术项目
`us.ci`	⭐⭐⭐⭐	较短，适合 API、CI/CD、服务器
`cc.cd`	⭐⭐⭐	容易记，但视觉上略重复
`ccwu.cc`	⭐⭐⭐	后台可注册时可用
`bot.cd`	⭐⭐	不建议默认按本教程接入 Cloudflare
`l.cd`	⭐⭐	注册和 Cloudflare 支持情况需单独确认

推荐命名

建议注册一个通用名称：

1
yourname.de5.net

然后通过子域区分服务：

1
kb.yourname.de5.net
2
cpa.yourname.de5.net
3
api.yourname.de5.net
4
status.yourname.de5.net

第一部分：注册 DNSHE 账号#

1. 打开 DNSHE 用户中心#

进入 DNSHE 用户中心并选择注册账户。

注册地址：

1
https://my.dnshe.com/register.php?language=chinese

建议使用长期稳定的公共邮箱注册，例如：

Gmail
Outlook / Hotmail
QQ 邮箱
网易邮箱
Apple 邮箱
Yahoo 邮箱
EDU 教育邮箱

Warning

不要使用临时邮箱，也不要使用刚搭建的自有域名邮箱注册。

一旦域名失效，可能无法接收找回密码邮件。

2. 填写账号资料#

通常需要填写：

邮箱
姓名
国家或地区
手机号码
密码

完成邮箱验证后登录。

3. 开启双重验证#

登录后进入账户安全设置，开启 2FA。

建议使用：

Google Authenticator
Microsoft Authenticator
1Password
Bitwarden
KeePassXC TOTP

第二部分：注册免费域名#

1. 进入免费域名页面#

登录后依次进入：

1
免费域名
2
→ 新增域名

当前免费额度通常可理解为：

1
3 个基础免费额度
2
+ 2 个邀请解锁额度
3
= 最多 5 个免费域名

普通使用注册一个即可，不需要为了额度专门邀请。

2. 填写域名前缀#

假设选择：

1
de5.net

自定义前缀填写：

1
yyq

最终得到：

1
yourname.de5.net

正确填写：

1
yyq

错误填写：

1
https://yourname.de5.net
2
www.yourname.de5.net
3
yourname.de5.net

命名建议

前缀尽量满足：

简短
容易记
不绑定单一服务
适合长期使用

推荐形式：

1
yourname.de5.net
2
qyy.de5.net
3
yyqkb.de5.net
4
myyyq.de5.net

3. 确认域名状态#

注册完成后，在域名列表检查：

1
域名：yourname.de5.net
2
状态：Active
3
到期时间：约一年后

续期规则

新注册免费域名通常默认有效期为一年。

到期前约 180 天可免费续期，续期次数通常不限。

最终以 DNSHE 后台显示为准。

第三部分：将域名添加到 Cloudflare#

1. 登录 Cloudflare#

进入：

1
Domains
2
→ Onboard a domain

中文界面可能显示：

1
域
2
→ 添加域

2. 填写完整域名#

输入：

1
yourname.de5.net

正确：

1
yourname.de5.net

错误：

1
de5.net
2
https://yourname.de5.net/
3
www.yourname.de5.net
4
kb.yourname.de5.net

这里添加的是你在 DNSHE 注册到的那一级域名。

3. 选择免费套餐#

选择：

1
Free
2
$0

继续。

4. 查看 Cloudflare 分配的名称服务器#

Cloudflare 会分配两条 NS，例如：

1
alice.ns.cloudflare.com
2
bob.ns.cloudflare.com

不要照抄示例

每个账号、每个域名分配到的 NS 不一样。

必须复制 Cloudflare 页面中实际显示的两条名称服务器。

第四部分：在 DNSHE 修改 NS#

1. 返回 DNSHE 域名管理#

进入：

1
免费域名
2
→ 域名管理
3
→ yourname.de5.net
4
→ DNS服务器

页面名称也可能显示为：

1
Nameservers
2
名称服务器
3
自定义 NS

2. 填入 Cloudflare NS#

删除原有名称服务器，填写 Cloudflare 分配的两条 NS：

1
alice.ns.cloudflare.com
2
bob.ns.cloudflare.com

填写规则：

每行一条
不带 https://
不填写 IP
不要作为普通 NS 解析记录添加
必须修改域名本身的权威名称服务器

错误做法：

1
类型：NS
2
名称：@
3
内容：alice.ns.cloudflare.com

正确做法：

1
在“DNS服务器 / Nameservers”页面
2
直接替换权威 NS

3. 检查 DNSSEC#

如果从未启用 DNSSEC，可以先跳过。

如果之前启用过 DNSSEC：

1
关闭旧 DNSSEC
2
→ 修改 NS
3
→ 等 Cloudflare 激活
4
→ 再重新配置 DNSSEC

初次使用建议先不开 DNSSEC，等解析和 HTTPS 全部正常后再启用。

4. 回到 Cloudflare 检查#

点击：

1
Check nameservers now
2
立即检查名称服务器

等待状态从：

1
Pending Nameserver Update

变成：

1
Active

托管完成标志

Cloudflare 中域名状态显示 Active 后，Cloudflare 才正式成为该域名的权威 DNS 服务商。

从此以后，下面这些记录都应在 Cloudflare 中管理：

A
AAAA
CNAME
TXT
MX
SRV
CAA

不要再在 DNSHE 的普通 DNS 解析页面维护这些记录。

第五部分：常见使用场景#

场景一：解析到 Oracle VPS#

假设服务器 IPv4：

1
203.0.113.10

进入 Cloudflare：

1
yourname.de5.net
2
→ DNS
3
→ Records
4
→ Add record

根域指向服务器#

1
类型：A
2
名称：@
3
IPv4：203.0.113.10
4
代理状态：Proxied
5
TTL：Auto

访问：

1
https://yourname.de5.net

为 CPA 单独建立子域#

1
类型：A
2
名称：cpa
3
IPv4：203.0.113.10
4
代理状态：Proxied
5
TTL：Auto

访问：

1
https://cpa.yourname.de5.net

场景二：服务监听 9527 端口#

Cloudflare 普通代理不支持任意端口。

常见可代理端口包括：

展开收起

9527 不能直接通过普通橙云代理。

方法 A：灰云直连#

将代理状态设置为：

1
DNS only

访问：

1
http://cpa.yourname.de5.net:9527

缺点：

暴露服务器真实 IP
不经过 Cloudflare HTTP 代理
需要直接开放 9527 端口

方法 B：Nginx 反向代理#

推荐让 Nginx 对外监听 80 / 443，再转发到：

1
127.0.0.1:9527

示例：

1
server {
2
    listen 80;
3
    server_name cpa.yourname.de5.net;
4

5
    location / {
6
        proxy_pass http://127.0.0.1:9527;
7
        proxy_set_header Host $host;
8
        proxy_set_header X-Real-IP $remote_addr;
9
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
10
        proxy_set_header X-Forwarded-Proto $scheme;
11
    }
12
}

完成 HTTPS 后，在 Cloudflare 中设置：

1
SSL/TLS
2
→ Overview
3
→ Full (strict)

Warning

不建议长期使用 Flexible。

推荐源站也配置 HTTPS，并使用 Full (strict)。

场景三：绑定 Obsidian + Quartz + Cloudflare Pages#

假设 Pages 默认域名：

1
my-quartz.pages.dev

建议绑定：

1
kb.yourname.de5.net

第 1 步：进入 Pages 项目#

1
Workers & Pages
2
→ 你的 Quartz 项目
3
→ Custom domains

第 2 步：添加自定义域名#

点击：

1
Set up a domain

填写：

1
kb.yourname.de5.net

继续完成验证。

Cloudflare 通常会自动创建所需的 DNS 记录。

不要只添加 CNAME

不要只在 DNS 页面手动添加：

1
kb → my-quartz.pages.dev

正确流程是先在 Pages 项目的 Custom domains 中完成绑定。

否则可能出现 522 或域名未关联的问题。

最终访问：

1
https://kb.yourname.de5.net

场景四：多个服务的域名规划#

建议统一规划：

域名	用途	Cloudflare 模式
`kb.yourname.de5.net`	Obsidian + Quartz	Pages 自动管理
`cpa.yourname.de5.net`	CPA 面板	橙云 + Nginx
`api.yourname.de5.net`	API 服务	橙云 + HTTPS
`ssh.yourname.de5.net`	SSH	灰云或 Tunnel
`status.yourname.de5.net`	状态页	橙云
`dev.yourname.de5.net`	开发测试	按实际需求

第六部分：验证配置#

检查 NS#

在 Windows PowerShell 中执行：

Terminal window

1
Resolve-DnsName -Name yourname.de5.net -Type NS -Server 1.1.1.1

正常应返回 Cloudflare 分配的两条 NS。

也可以使用：

Terminal window

1
nslookup -type=ns yourname.de5.net 1.1.1.1

检查根域解析#

Terminal window

1
Resolve-DnsName -Name yourname.de5.net -Server 1.1.1.1

检查子域解析#

Terminal window

1
Resolve-DnsName -Name kb.yourname.de5.net -Server 1.1.1.1

检查 HTTPS#

Terminal window

1
curl.exe -I https://kb.yourname.de5.net

正常可能看到：

1
HTTP/2 200
2
server: cloudflare

检查公网端口#

Terminal window

1
Test-NetConnection 服务器IP -Port 443

例如：

Terminal window

1
Test-NetConnection 203.0.113.10 -Port 443

第七部分：免费续期#

进入 DNSHE 域名列表，在到期前约 180 天检查是否出现：

1
Free Renewal
2
免费续期

点击后，到期日期通常会顺延一年。

建议记录：

1
注册日期
2
到期日期
3
开始可续期日期
4
实际续期日期

示例：

1
注册日期：2026-07-19
2
预计到期：2027-07-19
3
开始可续期：约 2027-01-20

Warning

具体日期必须以 DNSHE 后台显示为准。

不要只依赖记忆，建议设置日历提醒。

第八部分：常见问题排查#

1. Cloudflare 一直显示 Pending#

检查：

DNSHE 中是否真正修改了权威 NS
是否误把 NS 添加成普通解析记录
两条 NS 是否拼写正确
是否带了 https://
是否遗漏其中一条
DNSSEC 是否仍启用
是否等待足够的 DNS 传播时间

再次执行：

Terminal window

1
Resolve-DnsName -Name yourname.de5.net -Type NS -Server 1.1.1.1

如果返回的仍不是 Cloudflare NS，说明委派尚未生效。

2. 域名解析正常，但网站打不开#

检查：

服务器程序是否启动
Nginx / Caddy 是否运行
80 / 443 是否监听
Oracle 安全列表是否开放端口
Ubuntu 防火墙是否开放端口
Cloudflare SSL 模式是否正确
源站证书是否有效

Linux 检查监听端口：

Terminal window

1
sudo ss -lntp

检查 80 和 443：

Terminal window

1
sudo ss -lntp | grep -E ':80|:443'

3. 出现 522#

522 通常表示 Cloudflare 无法连接源站。

检查：

源站 IP 是否正确
服务器是否在线
端口是否开放
防火墙是否拦截 Cloudflare
Nginx 是否监听公网
Cloudflare Pages 是否只手动加了 CNAME，而没有在 Pages 中绑定自定义域名

4. 出现 SSL 证书错误#

检查：

Cloudflare SSL 模式
源站证书是否过期
证书域名是否匹配
是否使用了 Full (strict)
Nginx 是否加载了正确证书

5. 9527 端口打不开#

检查：

Terminal window

1
sudo ss -lntp | grep 9527

如果没有输出，说明程序没有监听 9527。

如果有监听但公网打不开：

Oracle 安全列表未放行
Ubuntu 防火墙未放行
程序只监听 127.0.0.1
Cloudflare 橙云不支持 9527

推荐做法：

1
外部访问 443
2
→ Nginx
3
→ 127.0.0.1:9527

第九部分：安全建议#

不要滥用免费域名

不要用于：

钓鱼
仿冒登录页面
垃圾邮件
未授权反代
绕过第三方服务限制
恶意 API
违法内容

DNSHE 可以直接删除域名并封禁账号。

第十部分：最终操作清单#

DNSHE#

注册 DNSHE 账号
验证邮箱
开启 2FA
注册 yourname.de5.net
记录到期日期

Cloudflare#

添加 yourname.de5.net
选择 Free 套餐
复制两条 Cloudflare NS
在 DNSHE 修改权威 NS
等待 Cloudflare 显示 Active
检查 DNSSEC 状态

解析与服务#

添加 A / CNAME 记录
配置 Nginx 或 Caddy
开放 80 / 443
配置 HTTPS
Cloudflare 设置 Full (strict)
验证根域和子域
配置 Quartz 自定义域名

后续维护#

设置续期提醒
定期登录 DNSHE
备份服务配置
保留 IP 直连方式
定期检查域名状态

十一、推荐的最终结构#

1
DNSHE：
2
yourname.de5.net
3

4
Cloudflare Zone：
5
yourname.de5.net
6

7
子域规划：
8
kb.yourname.de5.net      → Obsidian + Quartz
9
cpa.yourname.de5.net     → CPA 面板
10
api.yourname.de5.net     → API
11
status.yourname.de5.net  → 状态页
12
ssh.yourname.de5.net     → SSH / Tunnel

完整流程：

1
DNSHE 注册 yourname.de5.net
2
        ↓
3
Cloudflare 添加 yourname.de5.net
4
        ↓
5
复制 Cloudflare 两条 NS
6
        ↓
7
DNSHE 修改权威 NS
8
        ↓
9
Cloudflare 状态变 Active
10
        ↓
11
配置 A / CNAME / Pages
12
        ↓
13
配置 HTTPS
14
        ↓
15
每年免费续期

展开收起

十二、参考资料#

关联笔记#

ChatGPT Windows 升级后 Proxifier 网络异常排查

Fri, 10 Jul 2026 00:00:00 GMT

ChatGPT Windows 升级后 Proxifier 网络异常排查#

最终结论

本文记录三类容易混淆的问题。第一类是原有“按进程代理 + 选择性代理 DNS”没有完整覆盖新版访问方式；补充裸域名 chatgpt.com 并开启 Proxifier 的“DNS 和 IP 泄漏防护模式”后，启动速度、中文界面和审批模式恢复。第二类是重启后用量页再次失败；网络、账号和接口均验证正常，最终通过备份并移出升级后遗留的 Chromium 临时缓存恢复。第三类是 Codex 任务正文可以附图，但 ChatGPT 侧边栏上传失败；日志把它定位到侧边栏文件接口所经过的 DNS/代理链路，而不是图片格式或权限。第三类完成了配置核对，但未记录修改后的成功复测，因此不能写成已闭环修复。

一、故障现象#

升级后同时出现以下问题：

ChatGPT 启动明显变慢。
已在设置中选择中文，重启后界面仍显示英文。
左下角的用量摘要和重置信息消失。
“设置 → 用量与计费”显示无法加载用量设置。
审批模式的选项数量变少。

这些现象看似属于启动、语言、计费和权限四个模块。首轮故障来自同一条后端配置链路失败；用量页后来单独复发，则属于客户端缓存问题，不能继续归因于代理配置。

二、先区分界面变化和真实故障#

新版确实调整了部分界面，但不能一开始就把所有缺失内容都归因于 UI 改版。

判断顺序如下：

现象	判断方法	本次结论
“用量”页面直接报加载失败	检查应用日志、网络、登录态接口和缓存	首轮为网络故障，复发为客户端缓存
中文设置不生效	检查账户配置接口是否成功	网络故障导致回退
审批模式选项减少	先恢复功能配置接口，再观察	网络恢复后选项重新出现
左下角不再常驻显示 5 小时、7 天用量	“设置 → 用量”已正常时再判断	新版界面调整

Note

当前官方说明将 Codex 用量入口描述为“用量页面或达到限制时的提示横幅”，不再保证侧边栏始终显示用量卡片。普通额度仍会自动重置；储备重置次数只在符合资格且账户实际拥有重置次数时显示。

三、证据链#

1. 应用日志指向同一个网络入口#

日志中连续出现以下类型的错误：

1
Timed out while fetching post-login Statsig bootstrap
2
net::ERR_CONNECTION_CLOSED
3
net::ERR_TIMED_OUT

失败请求集中在：

1
/wham/accounts/check
2
/wham/statsig/bootstrap
3
/wham/profiles/me
4
/wham/usage

它们分别影响账户状态、功能开关、用户配置和用量信息，因此可以解释为什么语言、审批模式和用量同时异常。

2. 规则命中不等于 DNS 正确#

Proxifier 连接窗口已经能看到类似记录：

1
chatgpt.exe - chatgpt.com:443 open through proxy <本地 SOCKS5 地址>:<端口> SOCKS5

这只能证明 chatgpt.exe 的 TCP 连接命中了代理规则。如果连接很快关闭、只发送数据却收不到响应，仍需继续检查域名解析。

3. 本地 DNS 和代理 DNS 的 A/B 对照#

使用同一个 SOCKS5 代理测试 chatgpt.com:443：

方式	结果
本机先解析域名，再把 IP 交给 SOCKS5	TLS 建立前断开或超时
由 SOCKS5 代理端解析域名	TLS 证书验证成功并收到 HTTP 响应

这说明代理线路本身可用，问题位于本地 DNS 结果或 DNS 到代理的传递过程。

四、首轮根因分析#

1. 裸域名没有被原列表覆盖#

旧列表只有：

1
*.chatgpt.com

新版请求会直接访问裸域名：

1
chatgpt.com

在 Proxifier 的掩码匹配中，*.chatgpt.com 用于子域名，不能代替单独的 chatgpt.com 条目。因此必须同时配置两行。

2. 新版 DNS 查询可能绕过选择性代理解析#

配置文件显示“阻止非 A/AAAA DNS 查询”处于关闭状态。结合升级前后和修复前后的对照结果，推断新版 Chromium 网络栈发出的部分 DNS 查询没有被原有选择性代理 DNS 完整处理。

开启“DNS 和 IP 泄漏防护模式”后，Proxifier 会统一控制以下行为：

通过代理解析主机名。
使用代理 DNS 时阻止非 A/AAAA 查询。
阻止命中代理规则的 UDP 流量，避免 DNS、UDP 或 WebRTC 泄漏。

五、最终配置（Proxifier 中文界面）#

1. 代理服务器#

进入：

1
配置文件 → 代理服务器

添加本地代理工具提供的 SOCKS5 入口：

1
地址：<本地 SOCKS5 地址>
2
端口：<端口>
3
协议：SOCKS5

不要在公开笔记中填写真实端口、节点地址、订阅地址或认证信息。

2. 代理规则#

进入：

1
配置文件 → 代理规则

推荐顺序：

顺序	规则	应用程序	目标	动作
1	Localhost	Any	`localhost; 127.0.0.1; ::1`	Direct
2	Proxy Core	本地代理核心进程	Any	Direct
3	AI Tools	`ChatGPT.exe; Codex.exe; codex.exe`	Any	SOCKS5
4	Default	Any	Any	Direct

Warning

不要把代理核心进程放进 AI 工具代理规则，否则可能形成代理循环。也不要为了修复 ChatGPT 而把 Default 改成全局代理。

3. 名称解析#

进入：

1
配置文件 → 名称解析

设置：

1
关闭：自动检测 DNS 设置
2
开启：通过代理解析主机名称
3
选择：仅仅解析以下主机名

至少加入：

1
chatgpt.com
2
*.chatgpt.com
3
*.openai.com
4
*.oaistatic.com
5
*.oaistatsig.com
6
*.oaiusercontent.com
7
*.auth.openai.com

其中 chatgpt.com 和 *.chatgpt.com 必须同时保留。

4. DNS 和 IP 泄漏防护模式#

进入：

1
配置文件 → 高级 → DNS 和 IP 泄漏防护模式

启用后，Proxifier 会弹出确认窗口，提示它将控制代理 DNS、非 A/AAAA 查询和命中规则的 UDP 流量。选择“是”继续。

语音功能注意事项

该模式会阻止命中规则的 UDP 流量，可能影响 ChatGPT 语音、WebRTC 或其他依赖 UDP 的功能。本文验证的是 Codex 编程、设置、用量和普通 TCP 443 连接；如果需要语音，应单独测试并按需调整 UDP 规则。

5. 正确的重启顺序#

修改完成后：

从系统托盘彻底退出 Proxifier。
重新启动 Proxifier，确认当前配置文件已加载。
完全退出 ChatGPT，避免单实例应用复用旧进程。
重新启动 ChatGPT。
打开“设置 → 用量”，点击“重试”。

只重启 ChatGPT、不重启 Proxifier，可能继续使用旧的 DNS 防护状态。

六、用量页复发：二次排查与最终修复#

1. 复发现象#

首轮修复后，启动、中文界面、设置用量和三个审批模式都曾恢复。随后只重启 ChatGPT，用量页再次显示“无法加载使用设置”，但中文界面、审批模式和普通对话仍然正常。

这说明不能把第二次失败直接套用到第一次的 DNS 结论上。

2. 逐层排除#

检查项	结果	结论
Proxifier 配置文件	远程 DNS、域名列表、进程规则仍在	配置没有丢失
不带登录信息访问 `/backend-api/wham/usage`	经 SOCKS5 到达服务端并返回 `401`	DNS、SOCKS5、TLS 和服务端入口可达
带现有登录态访问同一接口	返回 `HTTP 200`	账号权限、令牌和用量服务正常
ChatGPT 点击“重试”后的连接	`chatgpt.exe → Proxifier → 本地 SOCKS5`	客户端请求确实命中代理
Windows DNS 缓存	清空后仍失败	单纯刷新 DNS 不能解决复发
关闭泄漏防护并重启两端	仍然失败	UDP/IP 泄漏防护不是复发根因
Windows“修复”	完成后仍失败	安装包级修复不足
Chromium 临时缓存	备份移出后恢复	问题范围定位到客户端临时缓存

401 为什么反而说明网络正常

未携带登录信息时返回 401 是预期结果，表示请求已完成 DNS、代理、TLS 和 HTTP 往返。若连接层失败，通常只能看到超时、连接关闭或状态码 000。

3. IPv6 UDP `connection blocked` 不是根因#

Proxifier 日志中出现：

1
chatgpt.exe - [2001:4860:4860::8888]:443 (UDP) (IPv6): connection blocked

该地址属于 Google Public DNS。UDP 443 通常来自 Chromium 的 QUIC、HTTP/3 或安全 DNS 探测；开启“DNS 和 IP 泄漏防护模式”后，Proxifier 阻止命中代理规则的 UDP 流量是预期行为。

本次关闭泄漏防护、让 UDP 绕过后，用量页仍然失败；与此同时 chatgpt.com:443 已经收到服务端数据。因此不要关闭系统 IPv6，也不要为该地址长期添加直连规则。最终配置应重新开启泄漏防护。

4. 不退出登录的缓存修复#

新版客户端实际使用的 Chromium 用户数据目录为：

1
%APPDATA%\Codex\web\Codex

为了避免触发重新登录、手机号验证或丢失本地状态，本次没有直接使用 Windows“重置”，而是先完全退出 ChatGPT，再将以下临时缓存移动到时间戳备份目录：

1
GraphiteDawnCache
2
GrShaderCache
3
ShaderCache
4
GPUPersistentCache
5
Default\Cache
6
Default\Code Cache
7
Default\GPUCache
8
Default\DawnGraphiteCache
9
Default\DawnWebGPUCache
10
Default\Shared Dictionary\cache
11
Default\Partitions\codex-browser-app\Cache
12
Default\Partitions\codex-browser-app\Code Cache
13
Default\Partitions\codex-browser-app\GPUCache
14
Default\Partitions\codex-browser-app\DawnGraphiteCache
15
Default\Partitions\codex-browser-app\DawnWebGPUCache
16
Default\Partitions\codex-browser-app\Shared Dictionary\cache

展开收起

备份目录使用类似名称：

1
%APPDATA%\Codex\web\Codex-cache-backup-YYYYMMDD-HHMMSS

以下内容必须保留：

1
Default\Network
2
Default\Local Storage
3
Default\Session Storage
4
%USERPROFILE%\.codex\auth.json

Warning

不要直接删除整个 %APPDATA%\Codex\web\Codex，否则可能清掉 Cookie、登录状态和本地浏览器数据。应先移动到备份，并且只处理明确列出的临时缓存目录。

本次共成功移动 16 个缓存目录，零跳过、零错误。ChatGPT 自动重建缓存后，用量页立即恢复，且没有重新登录。

如需回滚，应先退出 ChatGPT，将新生成的同名缓存目录另行改名，再从时间戳备份目录恢复；不要直接覆盖正在使用的新缓存。

七、Codex 正文可附图，但侧边栏上传失败#

1. 先区分两个上传入口#

同一张小图片在 Codex 任务正文中可以读取，拖入 ChatGPT 侧边栏后却显示 Upload failed。这两个入口不能只凭界面相似就视为同一条上传链路。

本次日志显示：

入口	实际行为	诊断意义
Codex 任务正文	先把本地附件交给任务	能成功说明文件可读、格式和大小没有明显问题
ChatGPT 侧边栏	立即请求文件上传接口	会直接暴露 DNS、TLS、代理切换和上传域名覆盖问题

因此，“一个入口成功、另一个入口失败”不等于侧边栏不支持图片，也不能优先归因于文件权限。

2. 证据链与根因范围#

与失败时间对应的应用日志出现：

1
POST /files -> net::ERR_NETWORK_CHANGED
2
net::ERR_CERT_COMMON_NAME_INVALID

同时观察到以下现象：

OpenAI 相关域名被解析到 127.x.x.x 回环假地址，而不是公网地址。
chatgpt.exe 与 codex.exe 都命中了 Proxifier 的 AI 工具规则。
侧边栏相关 HTTPS 连接存在“已发送数据、接收 0 字节”的记录。
IPv6/QUIC、mDNS 和非 A/AAAA 查询存在被阻止的记录。

Proxifier 在“通过代理解析主机名”时会为域名分配 127.x.x.x 假地址；这种地址只有在后续连接继续被 Proxifier 正确接管时才有效。由此可把故障范围收敛为：侧边栏文件接口经过的 Proxifier 与本地 SOCKS5 代理链路不稳定，或 DNS 假地址与进程接管没有保持一致。

Note

“进程命中代理规则”只证明连接选择了某条规则，不代表 DNS、TLS 和 HTTP 上传已经成功。仍要结合接收字节数、错误码和同一时刻的日志判断。

3. 不能使用 TUN 时的选择性代理配置#

在企业网络、安全客户端或 VPN 不允许开启 TUN 的环境中，可以保留单层进程代理：

1
企业网络保持原状
2
    -> Proxifier 只接管 ChatGPT / Codex
3
    -> 本地代理工具只提供 SOCKS5 监听

本地代理工具保持：

TUN/虚拟网卡关闭。
系统代理关闭。
本地 SOCKS5 端口保持监听。

Proxifier 规则按从上到下的顺序配置：

顺序	规则	目标	动作
1	Localhost	`localhost; 127.0.0.1; ::1`	Direct
2	Private Networks	`10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16`	Direct
3	AI Tools	`ChatGPT.exe; Codex.exe; codex.exe`，目标地址 Any	本地 SOCKS5
4	Default	Any	Direct

不要为当前 DHCP 下发的 DNS 地址逐个写死规则。使用三个标准私网网段可以覆盖常见的企业 DNS 和内网地址，并避免网络切换后规则立即失效。

Warning

不要把整个 127.0.0.0/8 设置为 Direct。Proxifier 的远程 DNS 可能使用该网段中的假地址；整体直连会绕开后续代理接管。Localhost 规则只保留明确需要的 127.0.0.1 与 ::1。

名称解析保持：

1
关闭：自动检测 DNS 设置
2
开启：通过代理解析主机名称
3
选择：仅仅解析以下主机名

域名列表至少覆盖：

1
chatgpt.com
2
*.chatgpt.com
3
*.openai.com
4
*.oaistatic.com
5
*.oaistatsig.com
6
*.oaiusercontent.com
7
*.auth.openai.com

chatgpt.com 与 *.chatgpt.com 要分别配置；通配子域名不能代替裸域名。

4. 不要仅凭 UDP 阻止日志改配置#

配置核对时可能看到：

1
non A/AAAA request blocked
2
UDP / QUIC connection blocked

这通常来自“DNS 和 IP 泄漏防护模式”对 HTTPS/SVCB 类型查询和 UDP 的限制。它们能够解释日志中的 connection blocked，但普通 HTTPS 上传通常可以回退到 TCP，所以不能仅凭这些记录断定必须关闭防护。

更稳妥的处理顺序是：

确认 Localhost、私网直连和 AI 工具规则的顺序。
确认本地 SOCKS5 端口确实由代理核心监听。
确认文件上传相关域名已纳入代理解析。
完全退出并重启 Proxifier 与 ChatGPT/Codex，清理旧的 127.x.x.x 映射。
使用同一张小图片复测侧边栏，并同步观察最新连接日志。
只有复测仍失败，且日志能把失败与非 A/AAAA 或 UDP 阻止对应起来时，才进行一次可回滚的 A/B 测试。

验证状态

本次已经确认图片本身无异常、定位了 /files 网络错误，并只读核对了规则顺序、代理监听和域名覆盖；但没有记录重启后的侧边栏成功上传结果。后续复测成功前，应把结论表述为“网络链路问题已定位、配置已核对”，而不是“问题已经修复”。

八、前两类故障的最终验证结果#

最终观察结果：

启动速度恢复正常
中文界面正常生效
“设置 → 用量”可以加载
审批模式选项恢复完整
对话与 Codex 工作流可以正常联网
Proxifier 中的 ChatGPT/Codex 连接命中指定 SOCKS5 规则
登录态用量接口经同一 SOCKS5 返回 HTTP 200
临时关闭泄漏防护后故障仍可复现，排除 UDP 阻止因素
选择性备份并移出 Chromium 缓存后，用量页恢复且登录态保留

左下角原有的 5 小时、7 天用量和重置摘要没有恢复，但“设置 → 用量”已经正常。这属于本次新版界面布局变化，不是网络故障仍未解决。

九、可复用的排查顺序#

以后遇到类似问题，按以下顺序排查：

先确认“设置 → 用量”是正常数据显示，还是直接报加载失败。
查看 Proxifier 是否出现 chatgpt.exe 或 codex.exe 到 chatgpt.com:443 的记录。
规则命中但收不到响应时，不要停在“进程已经走代理”的结论上，继续检查 DNS。
同时配置裸域名和通配子域名。
对比本地 DNS 后走 SOCKS5 与 SOCKS5 远程解析的结果。
检查“DNS 和 IP 泄漏防护模式”及非 A/AAAA 查询设置。
如果服务端已经返回数据，再做一次不输出令牌和响应正文的登录态接口校验，区分账号问题与客户端问题。
临时关闭泄漏防护只能用于 A/B 对照；若关闭后仍失败，应立即重新开启，不要继续扩大代理改动。
优先使用 Windows“修复”；无效时，备份并选择性移出 Chromium 临时缓存。
最后才考虑退出登录或 Windows“重置”，因为它们可能触发重新认证并删除应用数据。
网络和用量页都恢复后，再判断侧边栏差异是否属于新版 UI 调整。
如果只有侧边栏附件失败，用同一文件对比两个入口，并在点击上传的同时检查 /files、上传域名和 Proxifier 接收字节数。

十、公开发布与隐私#

本文使用 publish: true，仅保留可公开复用的配置和诊断方法。以下内容已经省略或替换为占位符：

Windows 用户名、计算机名和本机绝对路径。
真实代理端口、代理节点、订阅地址和认证信息。
公司域名、内网地址、VPN 路由和安全策略。
ChatGPT/Codex 会话 ID、线程 ID、日志文件名和进程实例 ID。
本机 DNS 返回的具体异常 IP。
DHCP 下发的 DNS 地址、本地 SOCKS5 端口和代理配置文件名。
Proxifier 完整导出配置。
实际 Chromium 缓存备份时间戳和本机用户名。
登录令牌、账号 ID 和用量接口响应正文。

十一、参考链接#

Codex Claude 软件级代理设置教程

Wed, 24 Jun 2026 00:00:00 GMT

Codex Claude 软件级代理设置教程#

结论#

优先使用“按软件代理”，只让 Codex、Claude 这类 AI 工具走本地代理端口，不要一上来就开启全局 TUN 或系统代理。

2026-07-07 实测可用配置

Proxifier 使用 SOCKS5，规则同时包含 Codex.exe 和 codex.exe；Localhost 与代理核心保持 Direct；不使用右键菜单的临时 Proxify Application；系统代理和 TUN 均关闭。这样 Codex 启动、用量加载和对话响应都恢复正常速度。

在当前这类 Windows + 公司网络 + 本地代理工具环境里，推荐优先使用 Proxifier：

首选 Proxifier：按进程接管 Codex、Claude，并让 DNS 通过代理解析。
可选启动脚本：适合命令行工具，或 Electron 应用明确吃环境变量和 --proxy-server 的情况。
Git 与 GitHub CLI 分开处理：Git 使用 URL 级规则，gh 用包装函数临时继承同一个代理值。
最后再用 TUN：只作为 Proxifier 和启动脚本都无法处理 DNS 或路由问题时的兜底方案。

场景选择#

场景	推荐方案
Codex 加入 Proxifier 后仍响应慢、反复 reconnect	Proxifier + 关闭自动 DNS 检测 + 开启通过代理解析主机名
Codex 可用，但 Claude Desktop 显示 `Couldn't connect to Claude`	Proxifier 路径规则命中后，再检查 Name Resolution 是否仍使用本地 DNS
公司内网、VPN、Jira、Git 不能被全局代理影响	Proxifier 按进程代理
Claude Code 从终端启动，想临时测试	当前终端设置 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`
Electron 桌面应用支持启动参数	环境变量 + `--proxy-server`
GitHub 需要代理，但 GitLab 或公司仓库必须直连	Git URL 级代理配置
Git 已能访问 GitHub，但 `gh auth login`、`gh api` 仍失败	PowerShell 包装函数让 `gh` 临时复用 Git 代理
Proxifier 和启动脚本都不稳定	临时开启 TUN，再单独处理公司域名直连规则

适用场景#

Windows 系统代理已经开启，但 Codex、Claude 仍然连接失败。
开启 TUN 后 AI 工具可用，但公司内网、Jira、Git、VPN 页面异常。
只希望 Codex、Claude、Node 子进程走代理，不影响浏览器、IDEA、企业安全软件和公司网络。
本地代理工具已经提供 HTTP 或 SOCKS5 端口，例如 Clash、FlyingBird、V2RayN、Shadowsocks。

先确认本地代理端口#

常见本地端口：

1
HTTP 代理：127.0.0.1:7890
2
SOCKS5 代理：127.0.0.1:7890 或 127.0.0.1:1080

以实际代理工具为准。先确认代理软件已经连接节点，并且本机端口正在监听：

Terminal window

1
Test-NetConnection 127.0.0.1 -Port 7890

如果你的工具区分 HTTP 与 SOCKS5，后面脚本里的协议也要对应修改。

方案一：Proxifier 按进程代理（当前优先）#

当系统代理对 Codex 不生效，或者 Codex 响应很慢、需要反复 reconnect、甚至无法登录时，优先使用 Proxifier。

中文界面版本#

如果英文界面不顺手，可以参考 1564307973/Proxifier-CN。这个仓库整理了 Proxifier 中文本地化包和便携版，适合对照中文菜单配置代理服务器、代理规则和 DNS 解析。

注意：

汉化包通常有版本适配限制，安装前先确认支持的 Proxifier 版本。
汉化不等于破解。Proxifier 仍是商业软件，长期使用需要正版授权。
如果已经安装官方新版 Proxifier，不要直接覆盖不匹配版本的汉化文件，避免程序异常。

添加代理服务器#

进入：

1
Profile -> Proxy Servers -> Add

填写本地代理：

1
Address: 127.0.0.1
2
Port: 7890
3
Protocol: SOCKS Version 5

如果你的本地 SOCKS5 端口是 1080，就改为 1080。

弹出是否设为默认代理时，建议选择“否”。不要让 Proxifier 一开始接管所有程序。

添加代理规则#

进入：

1
Profile -> Proxification Rules -> Add

为 Codex 添加规则：

1
Name: Codex
2
Applications: Codex.exe; codex.exe
3
Target Hosts: Any
4
Target Ports: Any
5
Action: Proxy SOCKS5 127.0.0.1:7890

两个进程都要包含：Codex.exe 是桌面界面，codex.exe 是后台 app-server。只代理前者时，窗口可能能打开，但“用量”、设置和对话请求会长时间等待。

不要从 Proxifier 右键菜单临时执行 Proxify Application。这种手动接管会跳过普通规则，包括 Localhost 直连规则；应当始终通过 Profile -> Proxification Rules 配置。

Claude Code 常见还需要把 Node 运行时纳入规则：

1
Name: Claude Code
2
Applications: claude.exe; node.exe
3
Action: Proxy SOCKS5 127.0.0.1:7890

如果担心 node.exe 范围太大，可以先只加 claude.exe，观察 Proxifier 日志里实际发起连接的进程，再补充更精确的路径规则。

DNS 也要走代理#

截图里的 Linux.do 经验重点是：问题不一定出在 Codex 进程没有代理，而是 DNS 解析没有按预期通过代理。

典型现象：

已经在 Proxifier 中加入 codex.exe，但响应非常慢。
需要多次 reconnect 才有响应。
甚至无法登录。
使用系统代理时也要尝试多次 reconnect。

处理方式：

1
Profile -> Name Resolution

在 Name Resolution 中：

1
关闭：Detect DNS setting automatically
2
开启：Resolve hostnames through proxy

这样让目标进程的主机名解析也通过代理完成。开启后再完全退出 Codex，并重新启动测试。

公司网络需要保留内网 DNS 时，优先使用 Resolve ONLY the following，只让下列公网域名通过代理解析：

1
*.chatgpt.com
2
*.openai.com
3
*.oaistatic.com
4
*.oaistatsig.com
5
*.oaiusercontent.com

这样不会把所有域名都交给代理端解析，也能减少对公司内网和 split DNS 的影响。

如果使用 SOCKS5，尽量选择支持远端 DNS 的方式。某些命令行工具支持 socks5h://127.0.0.1:7890，其中 h 表示 hostname 交给代理端解析；不支持时再退回 socks5://。

ChatGPT 新版专项排障

如果升级后同时出现启动慢、语言回退、用量加载失败或审批模式缺失，请参阅 ChatGPT Windows 升级后 Proxifier 网络异常排查。除了 *.chatgpt.com，还要单独覆盖裸域名 chatgpt.com，并检查“DNS 和 IP 泄漏防护模式”。

实测案例：Codex 可以，Claude 仍打不开#

本机配置中已经把 Codex 和 Claude 的程序路径都加入 Proxifier。现象是：

Codex 可以正常打开。
Claude Desktop 仍显示 Couldn't connect to Claude。
错误提示中出现 Your network redirected this request to www.anthropic.com。

这说明 Proxifier 的路径规则不一定有问题，真正的问题可能是名称解析仍然走了本地网络，被公司网络、DNS 策略、网关或安全软件重定向。

处理方式：

打开 Proxifier 日志，确认 Claude 对 www.anthropic.com:443、claude.ai:443 或相关域名的连接是否命中代理规则。
如果规则已命中，但 Claude 仍提示网络被重定向，进入 Profile -> Name Resolution。
关闭 Detect DNS setting automatically。
开启 Resolve hostnames through proxy。
完全退出 Claude Desktop 后重新打开。

同理，Proxifier 日志里如果已经能看到类似：

1
codex.exe - chatgpt.com:443 open through proxy 127.0.0.1:7890 SOCKS5

只能说明连接动作命中了代理规则，不代表 DNS 解析一定正确。遇到发送字节但收不到响应、反复 close、应用层报网络重定向时，应继续检查名称解析。

Name Resolution 选项理解#

Name Resolution 决定“域名变成 IP”这一步在哪里发生。

常见理解：

选项	含义	适合场景
`Detect DNS setting automatically`	让 Proxifier 自动判断使用本地 DNS 还是代理侧解析	普通网络环境，问题少时可以保留
`Resolve hostnames locally` / 本地解析	使用 Windows 当前 DNS 解析域名，再把 IP 交给代理连接	公司内网域名、需要 split DNS 的服务
`Resolve hostnames through proxy` / 通过代理解析	把域名交给代理服务器或代理链解析	公网服务被本地 DNS 污染、劫持、重定向或解析失败

对 Codex、Claude 这类公网 AI 工具，如果已经按进程代理但仍打不开，优先尝试 Resolve hostnames through proxy。

可能的副作用：

公司内网域名可能无法解析，因为代理节点不知道公司内部 DNS。
某些依赖本地 DNS 分流的服务可能走到错误地区或错误出口。
代理服务端会看到访问的域名，隐私边界从本机 DNS 转移到代理侧。
如果代理节点的 DNS 质量不好，可能出现解析慢、解析到不可用 IP、地区不匹配等问题。
Windows hosts 和公司 VPN 的 split DNS 结果可能不再按预期生效。

所以不要把 Proxifier 的默认规则改成全局代理。推荐只代理 Codex、Claude 等公网 AI 工具，代理软件自身、公司内网工具、VPN 客户端和企业安全软件保持 Direct。

规则顺序#

Proxifier 规则从上往下匹配，建议：

顺序	规则	Applications	Targets	Action
1	Localhost	Any	`localhost; 127.0.0.1; ::1`	Direct
2	Proxy Core	代理核心进程，例如 `FlyingBirdCore.exe`	Any	Direct
3	Codex	`Codex.exe; codex.exe`	Any	SOCKS5 `127.0.0.1:7890`
4	Default	Any	Any	Direct

不要把代理软件自身也放进代理规则，否则可能出现代理套代理、循环连接或节点频繁断开。

使用 Proxifier 时，让本地代理核心保持监听即可，同时关闭代理软件的“系统代理”和 TUN/虚拟网卡。多层接管会形成重复代理，常见表现就是 Codex 启动慢、用量迟迟不显示。

方案二：启动脚本注入代理#

这是最干净的方式。环境变量只传给当前脚本启动的软件及其子进程，不会修改 Windows 全局系统代理。

Codex Desktop#

完全退出 Codex 后，用 BAT 启动：

Terminal window

1
@echo off
2
chcp 65001 >nul
3
set HTTP_PROXY=http://127.0.0.1:7890
4
set HTTPS_PROXY=http://127.0.0.1:7890
5
set ALL_PROXY=socks5://127.0.0.1:7890
6
start "" "D:\软件\codex\Codex.exe" --proxy-server=http://127.0.0.1:7890

注意：

把 D:\软件\codex\Codex.exe 替换成你的真实 Codex 路径。
Codex Desktop 是单实例应用。已经运行时再执行 BAT，只会唤醒旧进程，新的代理变量不会注入。
测试时先退出所有 Codex 窗口，再从脚本启动。
--proxy-server 是 Chromium/Electron 常见启动参数，Codex 当前本地实践可用；如果后续版本行为变化，以实际验证为准。

Claude Code#

Claude Code 是命令行工具，优先在启动它的终端里设置环境变量：

Terminal window

1
$env:HTTP_PROXY = "http://127.0.0.1:7890"
2
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
3
$env:ALL_PROXY = "socks5://127.0.0.1:7890"
4
claude

如果希望每次 Claude Code 都带这些变量，可以写入 %USERPROFILE%\.claude\settings.json 的 env：

1
{
2
  "env": {
3
    "HTTP_PROXY": "http://127.0.0.1:7890",
4
    "HTTPS_PROXY": "http://127.0.0.1:7890",
5
    "ALL_PROXY": "socks5://127.0.0.1:7890"
6
  }
7
}

这个方式适合 Claude Code 本体和它启动的子进程。若只想临时测试，不要写入 settings.json，直接在当前终端设置环境变量即可。

Claude Desktop 或其他 Electron 应用#

如果是桌面版 Electron 应用，可以尝试用启动参数：

Terminal window

1
@echo off
2
chcp 65001 >nul
3
set HTTP_PROXY=http://127.0.0.1:7890
4
set HTTPS_PROXY=http://127.0.0.1:7890
5
set ALL_PROXY=socks5://127.0.0.1:7890
6
start "" "C:\Path\To\App.exe" --proxy-server=http://127.0.0.1:7890

这类参数并不是每个软件都会公开承诺支持。判断标准很简单：启动后能登录、能对话、公司网络不受影响，就保留；无效就切换到 Proxifier。

方案三：Git 和 GitHub CLI 仅 GitHub 走代理#

如果 GitHub 需要代理，但 GitLab、公司仓库和其他网站必须直连，不要设置通用的 http.proxy 或 https.proxy。Git 支持按 URL 配置代理：

Terminal window

1
git config --global http.https://github.com/.proxy http://127.0.0.1:7890

这里的 7890 应替换为本地代理工具实际提供的 HTTP 代理端口。该规则只匹配 https://github.com/；其他 HTTPS 地址不会继承它。

如果此前配置过全局 Git 代理，先检查配置来源：

Terminal window

1
git config --global --get-regexp '^(http|https)\..*proxy$'

确认通用代理不再需要后，将它们移除，再设置 GitHub 专用规则：

Terminal window

1
git config --global --unset-all http.proxy
2
git config --global --unset-all https.proxy
3
git config --global http.https://github.com/.proxy http://127.0.0.1:7890

最后验证实际生效的代理项：

Terminal window

1
git config --global --get-regexp '^(http|https)\..*proxy$'
2
git config --get-urlmatch http.proxy https://github.com/

预期只看到类似下面的 URL 级规则：

1
http.https://github.com/.proxy=http://127.0.0.1:7890

HTTPS 与 SSH 是两套配置

这项 Git 配置只影响 https://github.com/... 形式的远程地址，不影响 git@github.com:... 形式的 SSH 地址。SSH 需要在 ~/.ssh/config 中通过 ProxyCommand 单独设置代理，完整配置见 Git 与 GitHub SSH 代理配置教程。

Git 配了代理，为什么 `gh auth login` 仍打不开#

Git 和 GitHub CLI 是两个独立的网络客户端：

操作	读取 Git 的 `http.*.proxy`
`git clone`、`git pull`、`git push`	是
`gh auth login`、`gh api`、`gh issue`、`gh pr`	否
`gh repo clone`	实际执行 Git 的阶段读取；若还需发起 `gh` API 请求，该部分不读取

即使 .gitconfig 使用不限定域名的通用 http.proxy，也只是 Git 的配置，不会自动变成 GitHub CLI、PowerShell 或 Windows 的全局代理。gh auth login 还需要先在命令行中访问 GitHub 获取设备登录信息；这一步失败时，浏览器可能不会正常打开。

GitHub CLI 没有单独的 proxy 配置项。它的 HTTP 请求使用进程继承到的 HTTP_PROXY、HTTPS_PROXY 等环境变量。如果不希望永久修改用户环境变量，可以用 PowerShell 包装函数只在 gh.exe 运行期间注入代理。

让 `gh` 自动复用 Git 的代理#

把下面函数加入 PowerShell 的 $PROFILE：

Terminal window展开收起

1
function gh {
2
    # 读取 Git 对 GitHub 最终匹配到的全局代理；
3
    # 同时支持 http.https://github.com/.proxy 和通用 http.proxy。
4
    $proxyUrl = & git.exe config --global --get-urlmatch `
5
        http.proxy `
6
        https://github.com/ 2>$null
7

8
    if ([string]::IsNullOrWhiteSpace($proxyUrl)) {
9
        Write-Warning 'Git 全局配置中没有找到 GitHub 代理，gh 将直接连接。'
10
        & gh.exe @args
11
        return
12
    }
13

14
    $proxyUrl = $proxyUrl.Trim()
15
    $oldHttpProxy = $env:HTTP_PROXY
16
    $oldHttpsProxy = $env:HTTPS_PROXY
17

18
    try {
19
        $env:HTTP_PROXY = $proxyUrl
20
        $env:HTTPS_PROXY = $proxyUrl
21

22
        & gh.exe @args
23
    }
24
    finally {
25
        [Environment]::SetEnvironmentVariable(
26
            'HTTP_PROXY',
27
            $oldHttpProxy,
28
            'Process'
29
        )
30

31
        [Environment]::SetEnvironmentVariable(
32
            'HTTPS_PROXY',
33
            $oldHttpsProxy,
34
            'Process'
35
        )
36
    }
37
}

展开收起

这个函数有三个边界：

用 git.exe 读取 Git 针对 https://github.com/ 最终匹配到的代理，因此兼容 GitHub 专用规则和通用 http.proxy。
使用 --global，只读取用户级 Git 配置，不让某个仓库的局部设置意外改变全部 gh 命令。
显式调用 gh.exe，避免函数递归；命令结束后恢复原来的进程环境变量，不影响同一终端中的其他程序。

安装并验证包装函数#

创建并打开 PowerShell 配置文件：

Terminal window

1
if (!(Test-Path -LiteralPath $PROFILE)) {
2
    New-Item -ItemType File -Path $PROFILE -Force
3
}
4

5
notepad $PROFILE

粘贴函数并保存，然后立即重新加载：

Terminal window

1
. $PROFILE

确认 gh 已被包装函数接管，并检查 Git 能返回代理值：

Terminal window

1
Get-Command gh
2
git config --global --get-urlmatch http.proxy https://github.com/

Get-Command gh 的 CommandType 应为 Function。之后仍按原方式使用：

Terminal window

1
gh auth login -h github.com
2
gh api user
3
gh pr list

需要临时绕过包装函数并直接运行 GitHub CLI 时，显式调用：

Terminal window

1
gh.exe auth status

以后代理端口变化，只需修改 Git 配置：

Terminal window

1
git config --global http.https://github.com/.proxy http://127.0.0.1:新端口

PowerShell 函数无需同步修改。

方案四：TUN 兜底#

如果启动脚本和 Proxifier 都无法稳定处理 DNS，可以临时开启代理工具的 TUN 或虚拟网卡作为兜底。

公司网络下要注意：

TUN 可能接管默认路由和 DNS。
Fake-IP 可能把公司域名解析到 198.18.0.0/16。
系统代理排除列表只能影响应用层代理，不能完全约束 TUN。

公司网络、VPN、内网 DNS 与 TUN 共存属于环境相关场景，需要根据实际企业网络策略单独处理，本文不公开展开。长期方案仍建议回到“只让 AI 工具显式走代理”。

Windows 沙箱与工作区依赖#

`pwsh.exe` 商店别名导致沙箱启动失败#

如果 Codex 顶部持续出现“设置智能体沙盒以继续”，日志中又有类似错误：

1
CreateProcessAsUserW failed: 1920

可能是 Microsoft Store 安装的 PowerShell 7 注册了 pwsh.exe 应用执行别名。沙箱用户无法通过这个别名启动真实程序，而系统自带的 Windows PowerShell 可以正常运行。

处理步骤：

打开 Windows“设置 -> 应用 -> 高级应用设置 -> 应用执行别名”。
关闭 Microsoft PowerShell 对应的 pwsh.exe 别名。
完全退出并重新启动 Codex。
新会话应使用 C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe。

修复后可让 Codex 执行普通命令，并确认进程身份包含 codexsandboxoffline，再测试工作区文件的创建、读取和删除。出现这个身份说明智能体沙箱已经生效。

Windows 10 显示“工作区依赖未安装”#

这和沙箱不是同一个功能。当前 Codex 的工作区依赖要求 Windows 11 22H2 或更高版本；Windows 10 即使反复点击“诊断”或“重新安装”，仍可能显示“未安装”或“无法重新安装”。

在 Windows 10 上可以关闭“Codex 依赖项”开关并忽略该提示，代码编辑、命令执行和沙箱仍可正常使用。若确实需要随附的 Node.js、Python 工具链，再升级到受支持的 Windows 11 版本。

排查清单#

本地代理工具已连接节点
Test-NetConnection 127.0.0.1 -Port 7890 成功
Codex、Claude 已完全退出后重新启动
单实例桌面应用没有复用旧进程
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 协议和端口正确
Git 已能访问 GitHub 但 gh 失败时，已单独给 gh.exe 注入代理环境变量
Proxifier 的 Codex 规则同时包含 Codex.exe 和 codex.exe
使用常规 Proxification Rules，而不是临时 Proxify Application
Localhost 和代理核心规则位于 Codex 规则上方并保持 Direct
DNS 解析已经通过代理或远端解析
Claude 提示网络被重定向时，已关闭自动 DNS 检测并开启通过代理解析主机名
代理软件自身没有被 Proxifier 代理
使用 Proxifier 时已关闭系统代理和 TUN/虚拟网卡
Default 规则没有误改成全局代理
公司内网域名没有被 TUN Fake-IP 污染
沙箱报错 1920 时已关闭商店 PowerShell 的 pwsh.exe 应用执行别名

常见问题#

系统代理开了，为什么 Codex 还是不通？#

很多桌面软件、命令行工具或其子进程不一定读取 Windows 系统代理。Codex 这类 Electron 应用还可能有自己的网络栈。用启动脚本或 Proxifier 直接约束目标进程更可靠。

为什么不推荐长期全局 TUN？#

TUN 是更底层的接管方式，适合兜底，但会影响默认路由、DNS、公司 VPN、内网域名和安全软件。AI 工具只需要访问少量公网服务时，进程级代理的副作用更小。

`HTTP_PROXY` 和 `HTTPS_PROXY` 要填 HTTP 还是 SOCKS？#

如果代理工具提供 HTTP 入站端口，优先写：

1
http://127.0.0.1:7890

ALL_PROXY 可以写 SOCKS5：

1
socks5://127.0.0.1:7890

如果工具明确支持 socks5h://，可用它解决 DNS 走代理问题；不支持时可能会报协议错误。

Claude Code 的 `settings.json` 在哪里？#

Windows 下 ~/.claude 等价于：

1
%USERPROFILE%\.claude

用户级配置文件通常是：

1
%USERPROFILE%\.claude\settings.json

发布与隐私#

本文设置了 publish: true，只记录可公开复用的配置。发布前不要写入以下内容：

公司真实域名、内网 IP、VPN 路由和安全策略。
Windows 用户名、计算机名、仓库绝对路径和日志中的身份信息。
代理订阅、节点地址、认证用户名或密码。
Proxifier 导出的完整配置文件；其中可能包含代理凭据。

涉及实际公司网络的排障过程应放在没有 publish: true 的私有笔记中，公开文档只使用 <公司域名> 等占位符。

参考链接#

Note

整理时当前网络无法直接打开 Linux.do 两个页面；其中 Proxifier 代理 Codex 的 DNS 设置已根据截图补充。其余可访问资料主要来自 LZHPO、GitHub Wiki、Proxifier-CN、Claude Code 官方设置页和本知识库既有 Codex/TUN 排障记录。

Quartz 4 升级 Quartz 5 复盘

Wed, 03 Jun 2026 00:00:00 GMT

Quartz 4 升级 Quartz 5 复盘#

本文记录一次将 Obsidian 私人知识库的 Quartz 公开站点从 Quartz 4 升级到 Quartz 5 的过程。真实仓库名、本机路径、站点域名、Secret 名称均已脱敏。

一、升级目标#

私人 Obsidian 知识库：<PRIVATE_VAULT_REPO>
Quartz 公开站点仓库：<QUARTZ_REPO>
公开内容筛选方式：frontmatter 中的 publish: true
部署平台：Cloudflare Pages
原生产分支：v4
新生产分支：v5

目标是升级到 Quartz 5，同时保留“私人库写作、公开库发布、Cloudflare 自动部署”的链路。

二、Quartz 5 的关键变化#

项目	Quartz 4	Quartz 5
配置文件	`quartz.config.ts`、`quartz.layout.ts`	`quartz.config.yaml`
功能组织	内置 TypeScript 插件	GitHub 插件化
构建前置	通常直接 `npx quartz build`	需要先安装/恢复 `.quartz/plugins`
显式发布	TS 配置启用	YAML 中启用 `explicit-publish`

Important

Quartz 5 默认配置中 explicit-publish 不是开启状态。公开知识库必须显式启用。

三、迁移步骤#

3.1 建立隔离迁移分支#

不要直接在生产分支迁移。建议从上游 Quartz 5 创建隔离分支：

Terminal window

1
git worktree add -b <MIGRATION_BRANCH> "<QUARTZ_V5_WORKTREE>" upstream/v5

迁移完成后，将该分支推送为公开仓库的 v5 分支：

Terminal window

1
git -C "<QUARTZ_V5_WORKTREE>" push origin <MIGRATION_BRANCH>:v5

3.2 迁移站点配置#

Quartz 5 使用 quartz.config.yaml。关键配置：

1
configuration:
2
  pageTitle: <SITE_TITLE>
3
  locale: zh-CN
4
  baseUrl: <PROJECT_NAME>.pages.dev
5

6
plugins:
7
  - source: github:quartz-community/explicit-publish
8
    enabled: true

为了降低迁移风险，只保留实际启用的插件；暂时不把禁用插件写进 YAML。

3.3 迁移同步脚本#

同步脚本继续从私人知识库扫描 Markdown，并只复制文件开头 frontmatter 中含有 publish: true 的笔记。

判断公开标记时必须只解析开头 frontmatter，不要用跨全文正则搜索：

Terminal window

1
$frontmatter = [regex]::Match(
2
    $text,
3
    '\A---\s*\r?\n(?<content>.*?)\r?\n---\s*(?:\r?\n|$)',
4
    [System.Text.RegularExpressions.RegexOptions]::Singleline
5
)
6

7
$frontmatter.Success -and
8
$frontmatter.Groups["content"].Value -match '(?m)^publish:\s*true\s*$'

这样正文中的示例代码不会被误判为公开标记。

3.4 Cloudflare Pages 构建命令#

Quartz 5 的 .quartz/plugins 是运行时生成目录，不应提交到 Git。Cloudflare Pages 是干净构建环境，所以构建前必须安装插件。

最终构建命令：

1
node quartz/bootstrap-cli.mjs plugin install --from-config --clean && node quartz/bootstrap-cli.mjs build

输出目录仍然是：

1
public

四、遇到的问题与处理#

问题一：正文中的 `publish: true` 被误判为公开#

旧脚本使用跨全文正则，正文示例里的 publish: true 也会触发公开。

处理方式：

先截取文件开头的 frontmatter
只在 frontmatter 内判断 publish: true
做回归验证：正文示例不触发公开，frontmatter 标记才触发公开

问题二：`npx quartz plugin install` 在 Windows / Node 24 下卡住#

现象：

Terminal window

1
npx quartz plugin install

在本机环境中无输出卡住，进程残留。

处理方式：

Terminal window

1
node .\quartz\bootstrap-cli.mjs plugin install --from-config --clean
2
node .\quartz\bootstrap-cli.mjs build

直接调用仓库内 Quartz CLI 可以正常完成。

问题三：`npm run install-plugins` 触发 `.scss` ESM 解析错误#

现象：

1
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".scss"

处理方式：

不使用 npm run install-plugins 作为构建前置
改用 node quartz/bootstrap-cli.mjs plugin install --from-config --clean
再执行 node quartz/bootstrap-cli.mjs build

问题四：`quartz.lock.json` 残留未启用插件#

按 lockfile 恢复时，未启用的主题插件也可能被安装。

处理方式：

使用 --from-config --clean
从 quartz.config.yaml 移除当前不用的 enabled: false 插件块
让 lockfile 只保留当前配置实际需要的插件

问题五：Cloudflare 构建环境没有 `.quartz/plugins`#

本地构建可能依赖已有缓存，而 Cloudflare 新环境没有。

处理方式是在 Cloudflare 构建命令中显式安装插件：

1
node quartz/bootstrap-cli.mjs plugin install --from-config --clean && node quartz/bootstrap-cli.mjs build

并用全新临时副本验证：不带 .quartz、node_modules、public，从 npm install 开始完整构建。

问题六：生产分支切换顺序#

不能先改私人库 workflow，否则自动同步会推送到尚未准备好的分支。

推荐顺序：

推送旧生产分支上的安全修复。
推送新 v5 分支。
Cloudflare Pages 生产分支切到 v5。
私人库 workflow 从 v4 改为 v5。

五、最终验证#

干净环境验证流程：

Terminal window

1
npm install --registry=https://registry.npmjs.org
2
node .\quartz\bootstrap-cli.mjs plugin install --from-config --clean
3
node .\quartz\bootstrap-cli.mjs build

验证结果：

成功安装 33 个 Quartz 5 插件
公开内容：9 篇笔记
Quartz 输入文件：10 个，包括自动生成首页
输出静态文件：132 个
输出目录：public

六、自动发布链路切换#

私人库 GitHub Actions 原逻辑：

1
ref: v4
2
git push origin v4

迁移后改为：

1
ref: v5
2
git push origin v5

这样私人库推送后会自动同步公开内容到 Quartz 5 分支，并触发 Cloudflare Pages 构建。

七、主题美化调研#

Quartz 5 的主题主要有两条路线。

路线一：稳定配置化美化#

通过 quartz.config.yaml 修改：

theme.colors
theme.typography

再通过 quartz/styles/custom.scss 做少量样式增强。

推荐方案：

方案	特点	适用场景
清爽技术文档风	高可读、低装饰	技术笔记、工具手册
Obsidian 深色风	更接近 Obsidian	想保持本地写作体验
温暖数字花园风	暖白背景、博客感	随笔和知识沉淀
卡片化现代风	圆角、间距、层次更明显	想让站点更精致

个人建议：先采用“清爽技术文档风 + 少量卡片化圆角”。

路线二：社区主题插件#

Quartz 5 可以通过社区主题插件尝试 Obsidian 风格主题，例如：

tokyo-night
catppuccin
nord
rose-pine
dracula-official
aura

示例：

1
plugins:
2
  - source:
3
      name: quartz-themes
4
      repo: "https://github.com/saberzero1/quartz-themes.git"
5
      subdir: plugin
6
    enabled: true
7
    options:
8
      theme: tokyo-night
9
      mode: both
10
      calloutStyle: glass

这条路线可玩性更高，但引入额外插件和适配成本。建议等基础 v5 站点稳定后再尝试。

八、经验总结#

迁移 Quartz 大版本时，先用隔离 worktree，不要直接动生产分支。
公开内容筛选必须只看 frontmatter，不要全文搜索 publish: true。
Quartz 5 的插件目录是构建产物，不应依赖本地缓存。
Cloudflare Pages 要使用可在干净环境复现的构建命令。
新生产分支、Cloudflare 分支、私人库 workflow 三者要按顺序切换。
主题美化先求稳，再逐步尝试社区主题。

九、参考#

Obsidian 私人知识库自动发布 Quartz 与 Cloudflare Pages

Tue, 02 Jun 2026 00:00:00 GMT

Obsidian 私人知识库自动发布 Quartz 与 Cloudflare Pages#

这套方案将私人 Obsidian 知识库作为唯一写作入口，只公开明确标记的笔记。公开内容会自动同步到 Quartz 仓库，再由 Cloudflare Pages 构建为静态网站。

核心原则

私人知识库与公开网站必须使用两个独立仓库。只有 frontmatter 中显式声明 publish: true 的 Markdown 笔记可以进入公开仓库。

一、当前架构#

项目	当前配置
私人知识库本地目录	`<PRIVATE_VAULT_DIR>`
私人 GitHub 仓库	`<GITHUB_USER>/<PRIVATE_VAULT_REPO>`
私人仓库分支	`main`
Quartz 本地目录	`<QUARTZ_SITE_DIR>`
Quartz GitHub 仓库	`<GITHUB_USER>/<QUARTZ_REPO>`
Quartz 生产分支	`v5`
Cloudflare Pages 域名	`https://<PROJECT_NAME>.pages.dev`
Quartz 版本	`5.0.0`
Node.js 版本	`>=22`

Obsidian Git 自动提交与推送

GitHub Actions

同步 content/ 并推送

Cloudflare Pages Git 集成

Obsidian 私人知识库

私人仓库 / main

筛选 publish: true

Quartz 公开仓库 / v5

安装插件并构建

.pages.dev

Obsidian Git 自动提交与推送

GitHub Actions

同步 content/ 并推送

Cloudflare Pages Git 集成

Obsidian 私人知识库

私人仓库 / main

筛选 publish: true

Quartz 公开仓库 / v5

安装插件并构建

.pages.dev

二、日常发布#

2.1 发布一篇笔记#

在需要公开的笔记顶部加入：

1
---
2
title: 示例笔记
3
publish: true
4
---

保存后不需要手动复制文件。当前 Obsidian Git 插件会自动提交并推送私人知识库，后续流水线会继续完成公开同步和网站部署。

2.2 保持笔记私密#

以下情况不会被公开：

没有 frontmatter 的笔记
frontmatter 中没有 publish: true 的笔记
publish: false 的笔记
隐藏目录中的笔记，例如 .obsidian
临时规划文件：task_plan.md、findings.md、progress.md

发布前检查

不要在公开笔记中写入密码、Token、内网域名、私人附件路径或其他敏感信息。publish: true 是公开开关，不是草稿标记。

三、本地自动推送私人库#

私人知识库使用 Obsidian Git 插件自动备份。当前关键设置位于：

1
<PRIVATE_VAULT_DIR>\.obsidian\plugins\obsidian-git\data.json

当前行为：

设置	值	作用
`autoBackupAfterFileChange`	`true`	笔记发生变化后自动备份
`autoSaveInterval`	`5`	约每 5 分钟自动提交
`autoPushInterval`	`5`	约每 5 分钟自动推送
`autoPullInterval`	`10`	约每 10 分钟自动拉取
`autoPullOnBoot`	`true`	打开 Obsidian 时先拉取
`pullBeforePush`	`true`	推送前先拉取，减少冲突
`commitMessage`	`vault backup: {{date}}`	自动提交信息

需要立即发布时，也可以在私人知识库目录手动执行：

Terminal window

1
git add .
2
git commit -m "docs: publish note"
3
git push origin main

四、GitHub Actions 自动同步#

私人仓库中的工作流文件：

1
.github/workflows/publish-quartz.yml

触发条件：

向 <PRIVATE_VAULT_REPO>/main 推送提交
在 GitHub Actions 页面手动运行 workflow_dispatch

工作流会执行以下步骤：

检出私人知识库到 vault/
检出 <GITHUB_USER>/<QUARTZ_REPO> 的 v5 分支到 site/
运行 site/scripts/sync-public-content.ps1 -VaultPath .\vault
仅提交公开仓库中的 content/
如果公开内容没有变化，则正常退出，不创建空提交
如果有变化，则推送到 <QUARTZ_REPO>/v5

4.1 配置 GitHub Token#

私人仓库工作流需要向公开仓库写入内容，因此私人仓库中必须存在 Actions Secret：

1
<QUARTZ_PUBLISH_SECRET>

推荐创建 GitHub Fine-grained personal access token：

在 GitHub 个人设置中进入 Developer settings → Personal access tokens → Fine-grained tokens
将仓库访问范围限制为 <GITHUB_USER>/<QUARTZ_REPO>
为 Contents 授予 Read and write
将 Token 保存到私人仓库 <GITHUB_USER>/<PRIVATE_VAULT_REPO>
进入 Settings → Secrets and variables → Actions
新建 Repository secret，例如命名为 <QUARTZ_PUBLISH_SECRET>

不要提交 Token

Token 只能保存在 GitHub Actions Secret 中。不要将真实值写入 Markdown、脚本、Git 提交或聊天记录。

五、公开内容同步脚本#

同步脚本位于公开仓库：

1
scripts/sync-public-content.ps1

脚本的主要逻辑：

定位 Quartz 仓库中的 content/
校验目标目录必须位于 Quartz 仓库内部
清空旧的 content/
递归扫描私人知识库中的 Markdown 文件
仅解析文件开头的 frontmatter，并复制其中包含 publish: true 的文件
保持原始目录结构
自动生成公开首页 content/index.md

不要直接维护 content/

content/ 是同步脚本生成的目录。每次同步都会清空并重建。需要修改公开内容时，应修改私人知识库中的源笔记。

5.1 本地同步#

在 Quartz 仓库中执行：

Terminal window

1
cd <QUARTZ_SITE_DIR>
2
.\scripts\sync-public-content.ps1

脚本默认从相邻目录 ..\obsidian-yyq 读取私人知识库。需要指定其他目录时：

Terminal window

1
.\scripts\sync-public-content.ps1 -VaultPath "D:\notes\my-vault"

六、Quartz 配置#

公开仓库中的核心配置文件：

1
quartz.config.yaml

当前关键配置：

1
configuration:
2
  pageTitle: "<SITE_TITLE>"
3
  locale: "zh-CN"
4
  baseUrl: "<PROJECT_NAME>.pages.dev"
5
  ignorePatterns:
6
    - private
7
    - templates
8
    - .obsidian
9
plugins:
10
  - source: github:quartz-community/explicit-publish
11
    enabled: true

同步脚本与 explicit-publish 插件形成两层保护：

同步脚本只解析文件开头的 frontmatter，并复制带有 publish: true 的 Markdown
Quartz 构建时再次过滤未显式发布的页面

6.1 本地预览#

首次运行前安装依赖：

Terminal window

1
cd <QUARTZ_SITE_DIR>
2
npm install

同步内容并启动本地预览：

Terminal window

1
.\scripts\sync-public-content.ps1
2
node .\quartz\bootstrap-cli.mjs plugin install --from-config --clean
3
node .\quartz\bootstrap-cli.mjs build --serve

浏览器打开：

1
http://localhost:8080/

七、Cloudflare Pages 自动部署#

Cloudflare Pages 使用 Git 集成监听公开仓库。每次 <QUARTZ_REPO>/v5 收到新提交后，Cloudflare Pages 都会重新构建并发布网站。

7.1 Cloudflare Pages 配置#

在 Cloudflare Dashboard 中进入 Workers & Pages，创建 Pages 项目并导入已有 GitHub 仓库：

1
<GITHUB_USER>/<QUARTZ_REPO>

构建配置：

配置项	值
Production branch	`v5`
Framework preset	`None`
Build command	`node quartz/bootstrap-cli.mjs plugin install --from-config --clean && node quartz/bootstrap-cli.mjs build`
Build output directory	`public`
Root directory	留空，使用仓库根目录

部署成功后，Cloudflare Pages 会提供：

1
https://<PROJECT_NAME>.pages.dev

如果后续绑定自定义域名，需要同步修改 quartz.config.yaml 中的 baseUrl。

7.2 为什么不需要 Cloudflare Token#

当前使用 Cloudflare Pages 的 Git 集成。Cloudflare 直接监听公开 GitHub 仓库并自动部署，因此 GitHub Actions 不需要保存 Cloudflare API Token。

八、完整发布链路#

一次正常发布会出现两次 Git 推送：

Obsidian Git 将私人笔记推送到 <PRIVATE_VAULT_REPO>/main
私人仓库的 GitHub Actions 将筛选后的内容推送到 <QUARTZ_REPO>/v5
Cloudflare Pages 检测到公开库变化，安装 Quartz 5 插件并运行构建
Cloudflare Pages 将 public/ 目录发布到网站

查看进度的位置：

阶段	检查位置
私人库是否推送成功	`<GITHUB_USER>/<PRIVATE_VAULT_REPO>` 提交记录
自动筛选是否成功	私人库 GitHub Actions：`Publish Quartz notes`
公开内容是否更新	`<GITHUB_USER>/<QUARTZ_REPO>` 的 `v5` 分支
网站是否部署成功	Cloudflare Pages 项目的 Deployments 页面

九、附件处理#

当前同步脚本只复制 Markdown，不复制本地图片、PDF 或其他附件。

现有公开笔记中的图片使用远程 URL，因此可以正常显示。后续如果需要公开 Obsidian 本地附件，应增加附件白名单，只复制被公开笔记引用的资源，避免把私人附件整体上传。

十、常见问题#

10.1 保存笔记后网站没有更新#

按顺序检查：

笔记 frontmatter 是否包含 publish: true
Obsidian Git 是否已经推送到 <PRIVATE_VAULT_REPO>/main
私人仓库的 Publish Quartz notes 工作流是否成功
<QUARTZ_REPO>/v5 是否出现新的 content: sync published notes 提交
Cloudflare Pages 的最新 Deployment 是否成功

10.2 GitHub Actions 无法推送公开库#

重点检查：

私人仓库是否存在 <QUARTZ_PUBLISH_SECRET>
Token 是否过期
Token 是否仅授权给 <GITHUB_USER>/<QUARTZ_REPO>
Token 的 Contents 权限是否为 Read and write
工作流检出的公开分支是否仍为 v5

10.3 Cloudflare Pages 构建失败#

本地先复现：

Terminal window

1
cd <QUARTZ_SITE_DIR>
2
npm install
3
.\scripts\sync-public-content.ps1
4
node .\quartz\bootstrap-cli.mjs plugin install --from-config --clean
5
node .\quartz\bootstrap-cli.mjs build

如果本地构建成功，再检查 Cloudflare Pages：

Production branch 是否为 v5
Build command 是否为 node quartz/bootstrap-cli.mjs plugin install --from-config --clean && node quartz/bootstrap-cli.mjs build
Build output directory 是否为 public
Node.js 版本是否满足 Quartz 要求

10.4 公开页面出现不应发布的内容#

立即处理：

在私人源笔记中删除 publish: true 或改为 publish: false
推送私人库，等待自动同步删除公开副本
检查 GitHub 公开仓库的历史提交中是否仍包含敏感信息
如果敏感信息已经进入 Git 历史，轮换相关密码或 Token，并清理 Git 历史

十一、关键文件清单#

文件	用途
`<PRIVATE_VAULT_DIR>\.obsidian\plugins\obsidian-git\data.json`	Obsidian Git 自动备份设置
`<PRIVATE_VAULT_DIR>\.github\workflows\publish-quartz.yml`	私人库推送后自动发布
`<QUARTZ_SITE_DIR>\scripts\sync-public-content.ps1`	筛选并复制公开笔记
`<QUARTZ_SITE_DIR>\quartz.config.yaml`	Quartz 网站配置与二次过滤
`<QUARTZ_SITE_DIR>\content\`	自动生成的公开笔记目录

十二、参考文档#

Codex Windows 微软商店安装包提取与手动更新

Tue, 02 Jun 2026 00:00:00 GMT

Codex Windows 微软商店安装包提取与手动更新#

适用场景#

部分旧版 Windows 或受限办公环境无法直接通过 Microsoft Store 安装 Codex Desktop。此时可以从 Microsoft Store 产品页提取微软 CDN 中的安装包，并手动安装或解压运行。

Codex 的 Microsoft Store 产品 ID：

1
9PLM9XGG6VKS

官方商店页面：

1
https://apps.microsoft.com/detail/9PLM9XGG6VKS

提取 Microsoft Store 安装包#

使用第三方 Microsoft Store 链接生成器：

1
https://store.rg-adguard.net/

操作步骤：

打开链接生成器。
左侧下拉框选择 ProductId。
输入 9PLM9XGG6VKS。
右侧渠道选择 Retail。
点击勾号生成下载链接。
在结果中选择最新的 x64 Codex 安装包。

文件名通常类似：

1
OpenAI.Codex_<版本号>_x64__2p2nqsd0c76g0.msix

注意：

store.rg-adguard.net 是第三方链接生成器，不是微软官方网站。
实际安装包下载链接应指向微软 CDN。
不要从来源不明的网站下载别人重新打包的 .exe。
下载后可以在文件属性中检查数字签名。

两种更新方式#

方式一：正式安装 MSIX#

优先尝试使用 PowerShell 安装或覆盖升级：

Terminal window

1
Add-AppxPackage -Path "C:\下载目录\OpenAI.Codex_x64.msix"

这种方式更接近 Microsoft Store 正常安装流程，系统能够管理应用包。应用数据通常会保留。

方式二：解压后运行#

如果系统版本较低，无法安装 MSIX，可以将安装包解压后直接运行。

推荐更新流程：

完全退出 Codex。
在任务管理器中确认没有残留的 Codex.exe 和 codex.exe。
将新版安装包解压到新目录，例如：
```
1
D:\软件\codex-<新版本号>
```
运行新目录中的 Codex.exe。
确认登录状态、插件、配置和历史记录正常。
更新快捷方式。
旧目录暂时保留，确认稳定后再手动删除。

不要直接将新版文件逐个覆盖到旧目录。旧版残留文件可能与新版不兼容，也不利于回滚。

如果希望保持原路径不变，可以采用目录替换：

1
D:\软件\codex      -> D:\软件\codex-old
2
D:\软件\codex-new  -> D:\软件\codex

用户数据备份#

Codex 的用户数据通常位于用户目录，而不是程序目录：

1
C:\Users\<用户名>\.codex

更新前建议备份：

Terminal window

1
Copy-Item "$env:USERPROFILE\.codex" "$env:USERPROFILE\.codex-backup-$(Get-Date -Format yyyyMMdd-HHmmss)" -Recurse

更换程序目录后，登录状态、配置、插件和历史记录通常仍会自动读取。遇到异常时，不要立即删除 .codex 目录，先切回旧版程序目录排查。

查看本地版本#

解压运行时，可以查看 Codex.exe 的产品版本：

Terminal window

1
(Get-Item "D:\软件\codex\Codex.exe").VersionInfo |
2
  Select-Object FileVersion, ProductVersion

也可以检查当前进程：

Terminal window

1
Get-Process Codex -ErrorAction SilentlyContinue |
2
  Select-Object ProcessName, Path,
3
    @{Name='FileVersion';Expression={$_.MainModule.FileVersionInfo.FileVersion}},
4
    @{Name='ProductVersion';Expression={$_.MainModule.FileVersionInfo.ProductVersion}}

版本号有两种格式：

Codex.exe 产品版本，例如 26.519.81530
Microsoft Store AppX 包版本，例如 26.527.3686.0

两者格式不同，不应只比较最后一段数字。提取安装包时，以链接生成器列出的最新 x64 包为准。

沙箱注意事项#

解压运行不等于完全缺少沙箱组件。Codex 安装目录中通常包含：

1
resources\codex-command-runner.exe
2
resources\codex-windows-sandbox-setup.exe

但是旧版 Windows、初始化异常或解压安装方式可能导致沙箱无法正常启动。例如：

1
CreateProcessAsUserW failed: 1312

遇到沙箱异常时：

先更新 Codex。
优先尝试 MSIX 正式安装。
如果条件允许，升级到较新的 Windows 10 或 Windows 11。
不要因为开启“自动审查”就默认所有命令一定处于隔离环境中。
日常使用优先选择“默认权限”或“自动审查”，谨慎使用“完全访问权限”。

更新检查清单#

从 Microsoft Store 产品 ID 9PLM9XGG6VKS 提取最新 x64 包
确认下载链接来自微软 CDN
完全退出旧版 Codex
备份 %USERPROFILE%\.codex
优先尝试 Add-AppxPackage
解压运行时使用新目录，不要直接覆盖旧目录
验证登录状态、插件、配置和历史记录
验证沙箱命令是否正常执行
稳定运行后再删除旧版目录

参考链接#

KeePass 密码管理

Tue, 26 May 2026 00:00:00 GMT

KeePass 密码管理#

开源免费的密码管理器，支持 Windows / Android / Chrome，通过插件扩展实现自动填充、两步验证、跨平台同步。

相关笔记：电脑必备软件、KeePassXC 推荐配置与使用指南

官方下载：KeePass 官网

本文性质

这是一份个人整理笔记，按自己的使用顺序重写了 KeePass 与插件配置要点，不是原文转载。主要参考来源见文末「来源与致谢」。原文写于 2018 年，针对 KeePass 2.x 时代，插件版本与下载入口请以官网和仓库现状为准。

一、安装与中文配置#

1.1 安装中文语言包#

安装 KeePass（默认英文）
点击 View → Change Language → Open Folder
解压中文语言包 zip，将文件复制到该文件夹
重新点击 View → Change Language，选择 Chinese_Simplified，重启生效

1.2 插件安装#

所有插件均为 .plgx 格式，安装方式统一：

工具 → 插件管理器 → 打开文件夹
将 .plgx 文件复制到该文件夹
重启 KeePass

1.3 推荐插件清单#

插件	功能	来源
KPEnhancedEntryView	增强记录视图，一键查看/隐藏加密字段	SourceForge
KPEntryTemplates	模板编辑器，快速创建标准化记录	GitHub
KeePassHttp	与浏览器通信的 HTTP 桥接	GitHub
KeeTrayTOTP	桌面端生成 TOTP 两步验证码	GitHub
WebAutoType	根据网页自动填写标题/URL 快速添加记录	SourceForge
AutoTypeSearch	自动输入无匹配时弹出搜索框	SourceForge
YetAnotherFaviconDownloader	批量下载网站图标	GitHub
KPSourceForgeUpdateChecker	检查 SourceForge 来源插件的更新	SourceForge
chromeIPass	Chrome 浏览器端自动填充（crx 安装）	Chrome Web Store

二、数据库安全#

2.1 加密方式#

创建数据库时提供 3 种可组合的加密方式，建议使用 管理密码 + 密钥文件：

管理密码：打开数据库的主密码，不要遗忘
密钥文件：任意文件（图片、音频、文档等），原理是对文件做 SHA-256 哈希作为密钥。修改文件内容会导致无法解锁，重命名不影响。建议多方备份（其他盘、U盘、网盘）
Windows 用户账户：绑定当前 Windows 账户

2.2 迭代次数#

数据库设置 → 安全 → 迭代次数，默认 60000，建议设为 500000（安卓端打开约 5~6 秒）。次数越高，暴力破解难度越大。

2.3 安全桌面#

工具 → 选项 → 安全 → 勾选 在安全桌面输入管理密码。安全桌面环境下，键盘记录软件几乎无法工作。

2.4 数据库同步#

建议将数据库文件存储在 OneDrive 文件夹中，利用 OneDrive 的版本历史记录和回收站功能防止误操作。安卓端可使用 FolderSync 进行双向同步。

三、自动输入#

3.1 基本原理#

KeePass 通过模拟按键实现自动输入。全局热键默认为 Ctrl + Shift + A（可能与 QQ 等软件冲突，可在 工具 → 选项 → 集成 中修改）。

使用方式：

点击目标输入框 → 按下全局自动输入热键
或在 KeePass 主界面右键记录 → 执行自动输入

如果目标程序以管理员权限运行，KeePass 也必须以管理员权限运行才能自动输入。

3.2 匹配规则#

按下自动输入热键时，KeePass 根据当前活动窗口标题在数据库中匹配记录——记录的标题或网址包含在窗口标题内即匹配成功。

注意事项：

标题需包含网页关键词（不能随意填写），否则无法匹配
Chrome 中所有标签页标题都包含 “Google Chrome”，可能误匹配
务必勾选 工具 → 选项 → 高级 → 总是显示全局自动输入记录选取对话框

3.3 推荐键入规则#

默认规则：{USERNAME}{TAB}{PASSWORD}{ENTER}

推荐规则（适合中文用户）：

1
+{DELAY 100}{CLEARFIELD}{USERNAME}{TAB}{PASSWORD}{ENTER}

+ = Shift 键（切换输入法）
{DELAY 100} = 等待 100ms
{CLEARFIELD} = 清空输入框
注意：使用此规则时确保当前输入法为中文状态

设置方式：编辑群组 → 自动输入 → 替代默认规则，子记录会自动继承。

3.4 全自动切换英文输入并切回#

通过 Windows 键盘快捷键 + KeePass 编码实现自动切换。

Step 1 — Windows 键盘设置：

控制面板 → 语言 → 高级键盘设置 → 语言栏选项 → 分别设置英语美式键盘和中文键盘的快捷键（如 Ctrl+0 切换英文，Ctrl+1 切换中文）。

Step 2 — KeePass 规则：

1
^0{CLEARFIELD}{USERNAME}{TAB}{PASSWORD}^1{ENTER}

^0 = Ctrl+0（切换到英文输入）
^1 = Ctrl+1（切换回中文输入）
^+1 = Ctrl+Shift+1（部分输入法如搜狗需要加 Shift）

这样自动填写时无需手动切换输入法。

3.5 双通道自动输入混淆#

将要输入的字符随机分为两部分，分别用模拟按键和复制粘贴两种方式混合输入，输入完成后还原剪切板内容。单一的键盘记录或剪切板监听均无法窃取完整字段。

某些软件输入框不支持粘贴，因此该功能默认不启用。

启用方式：编辑记录 → 自动输入 → 勾选 双通道自动输入混淆。配合 KPEntryTemplates 模板插件可实现新建记录时自动启用。

3.6 指定窗口自定义规则#

部分软件中全局自动输入可能失效，可通过 编辑记录 → 自动输入 → 为指定窗口使用自定义规则 → 添加 → 选择窗口 进行适配。

四、浏览器集成（KeePassHttp + chromeIPass）#

4.1 工作原理#

KeePassHttp 作为插件运行在 KeePass 中，chromeIPass 作为 Chrome 扩展运行在浏览器中。chromeIPass 不存储数据，每次通过 KeePassHttp 从 KeePass 数据库获取记录（AES 256 加密传输）。

4.2 chromeIPass 配置#

点击 Chrome 中 chromeIPass 图标 → Connect
输入标识名称（如”家里的电脑”）→ Save
默认快捷键：Ctrl + Shift + U（填充用户名+密码）、Ctrl + Shift + P（仅填充密码）

4.3 自动新建/更新记录#

在未记录的网站登录时，chromeIPass 图标会变红闪烁，点击即可新建或更新记录。注意：chromeIPass 无法识别登录是否成功，输错密码也会闪烁。

4.4 进阶技巧#

网址前缀处理：添加记录时网址设为 baidu.com/ 而非 www.baidu.com/，这样子域名（tieba.baidu.com、map.baidu.com）均可匹配。使用 WebAutoType 插件可自动完成。

修改网站密码：

在 chromeIPass 设置中取消勾选 Automatically fill-in single credentials entry
打开密码修改页面，按 Ctrl + Shift + P 填入原密码
在 KeePass 中修改密码
切换到其他标签页再切回
按 Ctrl + Shift + P 填入新密码

原理：切换标签页会触发 KeePassHttp 重新检索数据库。

关闭密码生成器：chromeIPass 的密码生成功能复制到剪切板后不会自动清除，建议在设置中关闭 Activate password generator。

五、两步验证（KeeTrayTOTP）#

5.1 功能说明#

在 Windows 端直接生成 TOTP 两步验证码，安卓端 Keepass2Android 无需额外配置即可使用。替代 Google Authenticator、Microsoft Authenticator、Steam 手机客户端等。

5.2 配置方法#

设置网站两步验证时，在二维码下方点击”无法扫描条形码”，获取密钥（TOTP Seed）
在 KeePass 中选中记录，按 Ctrl + Shift + I 打开 TOTP 设置
粘贴密钥到 TOTP Seed，TOTP Format 选择 6（6 位验证码）
点击 Finish

使用：选中记录 → Ctrl + T（或右键 → Copy TOTP），验证码即复制到剪切板。

5.3 特殊网站处理#

小米：只能扫码不给密钥时，用任意二维码扫描软件获取密钥（URI 中 secret= 参数）。

Steam（需手机 root）：

安装 Steam 手机客户端并设置好令牌
用 root 文件管理器打开 /data/data/com.valvesoftware.android.steam.community/files/Steamguard
复制密钥，TOTP Format 选择 Steam
验证与手机端令牌代码一致后可卸载手机客户端

六、KPEntryTemplates 模板配置#

6.1 基础配置#

文件 → 数据库设置 → 高级，在 模板记录组 中选择一个群组
在该群组中按 Ctrl+I 添加记录
配置 自动输入 勾选 双通道自动输入混淆
点击 Template → Init As Template
配置所需字段 → 确定

6.2 关键字段类型#

Protected Inline：加密文本编辑框，用于存储支付密码等敏感字段
Listbox：下拉列表框，适合邮箱、手机号等重复字段。分隔符为英文逗号

6.3 使用模板#

添加记录时 → Template → Set Template Parent，选择对应模板即可。

七、高级技巧#

7.1 固定配置（防篡改）#

类似网吧还原机制，每次启动使用固定配置：

工具 → 选项，配置完成后点确定
打开 C:\Users\<用户名>\AppData\Roaming\KeePass
将 KeePass.config.xml 重命名为 KeePass.config.enforced.xml
剪切到 C:\Program Files (x86)\KeePass Password Safe 2

如需取消，删除 KeePass.config.enforced.xml 即可。

7.2 TAN（一次性验证码）#

适用于网站两步验证提供的备用验证码，每条 TAN 用过后自动标记失效日期。

建议为每个账户单独创建群组，避免混淆
添加方式：选中群组 → 工具 → TAN 向导 → 勾选 序号连续，开始于

7.3 WebAutoType 快速添加#

设置全局热键后，在网页中一键添加记录（标题和 URL 自动填充）：

工具 → WebAutoType Options → 设置 Global hot key → OK

7.4 AutoTypeSearch 搜索补充#

按下自动输入热键无匹配时弹出搜索框，手动搜索后执行自动输入。

可设置独立全局热键：工具 → 选项 → AutoTypeSearch → 勾选并设置。

八、安卓端（Keepass2Android）#

支持 TOTP、指纹解锁、自动清除剪切板、禁止应用内截图
Android 8.0+ 支持应用内自动填充，8.0 以下使用内置键盘填充
离线版同步建议使用 FolderSync（双向同步）
官方版本内置中文，完全免费，仅从 Google Play 下载

九、常见问题#

9.1 安全警告#

仅从官方渠道下载 KeePass 及插件，避免使用精简版、修改版、增强版等
密钥文件不要随意修改内容，重命名不影响使用

9.2 快捷键冲突#

默认 Ctrl+Alt+A 可能与 QQ 截图快捷键冲突，在 工具 → 选项 → 集成 中修改。

9.3 自动输入失效#

目标程序以管理员权限运行时，KeePass 也需以管理员权限运行。

十、来源与致谢#

本文是在他人公开教程基础上重写的个人整理笔记，不是原文转载；章节结构、取舍和补记的踩坑点由本人决定。参考来源：

《一劳永逸：KeePass全网最详使用指南》，知乎专栏，2018-07-13，作者署名 tactk：zhuanlan.zhihu.com/p/39645975。知乎正文可能需要登录才能查看。
作者个人站点战术客上的相关 KeePass 文章（同样是 tactk，标题即《KeePass入门探索——全自动切换英文输入并切回及自动调用技巧》），2018-09-26：tacgeek.com/1937-keepass.html。
KeePass 官方插件列表：keepass.info/plugins.html。

原文截图托管在知乎图床，禁止外站引用（直接请求返回 403），而本仓库的发布管道只同步 Markdown、不同步图片，所以这里只保留文字步骤，界面细节请对照官方文档或原作者原文。需要完整配图版请直接阅读原作者文章。

Arthas诊断

Mon, 24 Jul 2023 00:00:00 GMT

Arthas诊断#

阿里开源 Arthas 工具，线上诊断 Java 程序的神器。

一、Arthas简介#

Arthas官网 | Arthas GitHub

image-20230724144124654

1.1 使用准备#

Terminal window展开收起

1
## 1、下载 arthas 的包
2
wget https://alibaba.github.io/arthas/arthas-boot.jar
3

4
## 2、启动 arthas
5
java -jar arthas-boot.jar
6

7
## 3、arthas 启动后会自动检测存在的 java 进程
8
$ java -jar arthas-boot.jar
9
* [1]: 35542 com.yyq.bootstrap.jar
10
  [2]: 71560 arthas-demo.jar
11
1
12

13
## 4、选择进程，使用相关命令
14

15
## 5、stop 命令可退出

展开收起

二、基础命令#

2.1 jad（反编译）#

1
## 查看 java 源码，可以用来诊断线上环境代码是否最新
2
jad demo.MathGame test

2.2 watch（数据观测）#

Terminal window

1
## 监听 demo.MathGame 类的 primeFactors 方法，展示 params[0] 第一个参数、returnObj 返回值、throwExp 报错，过滤条件 params[0].getKey == '12345'，打印详细参数-v，收集n条数据-n
2
watch demo.MathGame primeFactors "{params[0],returnObj,throwExp}" "params[0].getKey == '12345'" -x 2 -v -n
3

4
## 过滤list数组中包含参数条件
5
wacth ... "params[0].parameters.indexOf('c1r4k4yv')>-1"

2.3 trace（调用路径）#

stack：当前方法被调用的调用路径（反向trace）

Terminal window

1
## 监控方法内部调用路径，并输出方法路径上的每个节点上耗时
2
trace demo.MathGame test

2.4 sc（JVM 已加载的类信息）#

Terminal window展开收起

1
## 查看JVM已加载的类信息
2
$ sc -d demo.MathGame
3
class-info        demo.MathGame
4
code-source       /private/tmp/math-game.jar
5
name              demo.MathGame
6
isInterface       false
7
isAnnotation      false
8
isEnum            false
9
isAnonymousClass  false
10
isArray           false
11
isLocalClass      false
12
isMemberClass     false
13
isPrimitive       false
14
isSynthetic       false
15
simple-name       MathGame
16
modifier          public
17
annotation
18
interfaces
19
super-class       +-java.lang.Object
20
class-loader      +-sun.misc.Launcher$AppClassLoader@3d4eac69
21
                    +-sun.misc.Launcher$ExtClassLoader@66350f69
22
classLoaderHash   3d4eac69
23

24
Affect(row-cnt:1) cost in 875 ms.

展开收起

2.5 logger（logger 信息）#

Terminal window

1
## 查询所有日志设置
2
$ logger
3

4
## 更改日志级别
5
$ logger -c [hashcode] --name ROOT --level debug

2.6 tt（方法执行数据的时空隧道）#

2.7 ognl表达式#

如watch命令的过滤、计数等…

Arthas特殊用法issues

OGNL表达式官网

三、高级应用#

3.1 Idea插件#

arthas idea

3.2 线上热部署#

3.3 获取任意bean#

GitHub教程

spring mvc应用，请求会经过一系列的spring bean处理，那么我们可以在spring mvc的类里拦截到一些请求。

Terminal window

1
$ tt -t org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter invokeHandlerMethod
2
Press Ctrl+C to abort.
3
Affect(class-cnt:1 , method-cnt:1) cost in 101 ms.
4
 INDEX  TIMESTAMP         COST(ms  IS-RE  IS-EX  OBJECT       CLASS                     METHOD
5
                          )        T      P
6
------------------------------------------------------------------------------------------------------------------
7
 1000   2019-01-27 16:31  3.66744  true   false  0x4465cf70   RequestMappingHandlerAda  invokeHandlerMethod
8
        :54                                                   pter

那么怎样获取到spring context？

可以用tt命令的-i参数来指定index，并且用-w参数来执行ognl表达式来获取spring context：

Terminal window

1
$ tt -i 1000 -w 'target.getApplicationContext()'
2
@AnnotationConfigEmbeddedWebApplicationContext[
3
 reader=@AnnotatedBeanDefinitionReader[org.springframework.context.annotation.AnnotatedBeanDefinitionReader@35dc90ec],
4
 scanner=@ClassPathBeanDefinitionScanner[org.springframework.context.annotation.ClassPathBeanDefinitionScanner@72078a14],
5
  annotatedClasses=null,
6
  basePackages=null,
7
]
8
Affect(row-cnt:1) cost in 7 ms.

从spring context里获取任意bean

获取到spring context之后，就可以获取到任意的bean了，比如获取到helloWorldService，并调用getHelloMessage()函数：

Terminal window

1
$ tt -i 1000 -w 'target.getApplicationContext().getBean("helloWorldService").getHelloMessage()'
2
@String[Hello World]
3
Affect(row-cnt:1) cost in 5 ms.

3.4 获取数据库连接信息#

找到项目中数据库相关组件，如：mybatis-spring

查询数据库组件中存在DataSource的相关类和方法

Terminal window

1
org.mybatis.spring.transaction.SpringManagedTransactionFactory#newTransaction(javax.sql.DataSource, org.apache.ibatis.session.TransactionIsolationLevel, boolean)

通过tt方法检索DataSource中隐藏的数据库连接信息

Terminal window

1
tt -t org.mybatis.spring.transaction.SpringManagedTransactionFactory newTransaction -n 5
2

3
tt -i 1001 -w 'params[0].**'

四、常见问题#

电脑必备软件

Sun, 23 Jul 2023 00:00:00 GMT

电脑必备软件#

Windows 电脑必备软件，包括电脑美化、实用工具等。

一、效率工具#

1.1 Snipaste（截图工具）#

小巧、快捷、使用方便

Snipaste

1.2 Keepass（统一密码管理）#

统一密码管理软件，需要配置插件使用

Keepass

使用教程

KeePass 密码管理
2026-05-26knowledge#keepass#密码管理#效率工具#安全
KeePassXC 推荐配置与使用指南：当前主力客户端配置
一劳永逸：KeePass全网最详使用指南
使用 OneDrive 同步

1.3 Neat Download Manager（下载工具）#

小巧下载工具，配合浏览器插件使用更佳

Neat Download Manager

1.4 Listary（快捷启动工具）#

通过快捷键唤起搜索框，快速查询并启动软件

Listary

1.5 PicGo（图床工具）#

配合 GitHub 仓库搭建免费图床

PicGo

使用教程

1.6 Typora（MarkDown编辑器）#

配合 Snipaste + PicGo 实现文章图片的截取上传自动化

Typora

二、电脑美化#

2.1 Wallpaper Engine (Steam)#

Wallpaper Engine

三、配置优化#

3.1 暂无#

Hexo + GithubPage 博客搭建

Sun, 23 Jul 2023 00:00:00 GMT

Hexo + GithubPage 博客搭建#

基于 Hexo 博客框架搭建 GithubPage 免费的静态博客页面。

一、Hexo 的使用#

Hexo官网链接

二、Hexo 主题#

闪烁之狐大神的 hexo-theme-matery

三、GithubPage 的使用#

四、GitHub Action#

五、优化#

六、教程汇总#

6.1 夜法之书 #

七、常见问题#

7.1 Hexo 文档永久链接设置#

官网文档 — 永久链接（Permalinks）

permalink 最后一定要以 / 收尾，否则点击文档会变成下载

7.2 Git Bash 中按下 Ctrl+C 无法中断 hexo s#

打开 cmd，命令行执行 taskkill /F /IM node.exe

转载至