RGC Blog

博客开始了

Wed, 20 May 2026 00:00:00 GMT

这是这个博客的第一篇文章，也算是给它留一个起点。

我不太想把它做成一个只摆成品的地方。更想让它像一个可以慢慢堆东西的工作台：项目做到一半的想法、某次配置踩过的坑、一个后来终于跑通的接口、或者某个突然想试试的页面效果，都可以先放进来。

大概会先写这些内容：

项目里真正值得回看的设计和问题
平时用到的配置、命令和代码片段
学习过程中还没完全吃透、但值得记录的东西
一些带动画、音乐、视频或交互效果的小实验

第一版先用 Astro 和 Fuwari 搭起来。它现在还很朴素，但这也挺好：先让内容有地方落脚，再一点点把样子和结构调成自己喜欢的状态。

const blog = {
  stack: ["Astro", "Fuwari", "Markdown"],
  purpose: "write first, polish later",
};

在 Frappe / ERPNext 上折腾一个业务网关

Wed, 20 May 2026 00:00:00 GMT

一开始只是想把 Frappe / ERPNext 的 Docker 环境跑顺。跑起来之后，问题就变成了另一个：如果真的要围绕 ERPNext 做一个自己的业务系统，代码应该怎么组织才不至于越写越散？

于是有了这个 myapp。它现在更像一组持续整理中的实践：后端有自定义 App 和业务网关，前端有 Web 和移动端方向，旁边还放着接口集合、HTTP 测试和一些性能记录。

为什么要加一层网关

myapp 是一个基于 Frappe / ERPNext 的业务系统扩展。它没有直接让前端散落调用 ERPNext 原生接口，而是用 myapp.api.gateway.* 组织出一层更稳定的业务网关。

这层网关覆盖了商品、客户、销售、采购、供应商、结算、报表、媒体上传和移动端版本信息等能力。

这样做的价值在于，前端看到的是业务动作，而不是 ERPNext 里面更底层的 DocType 细节：

前端面对的是业务语义，而不是 ERPNext 的底层 DocType 细节
错误码、响应格式和权限处理可以统一
销售、采购等主链路可以围绕幂等和真实 HTTP 测试做回归
后续替换图片存储、打印服务或移动端能力时，接口契约更稳定

现在的结构

从目录和文档看，项目大概分成三块：

apps/myapp：自定义 Frappe App，放业务接口和测试
frontend/myapp-web：Web 管理端，基于 React、Umi Max、Ant Design Pro
frontend/myapp-mobile：移动端，基于 Expo、React Native、expo-router

这让我比较在意的一点是：它不是只停留在后台配置页面，而是开始往“业务现场怎么用”这个方向走。比如移动端依赖里已经出现了相机、图片、打印、PDF、图表这些能力，这些都更接近收货、上传、查看和现场处理。

接口怎么组织

文档里把接口按业务域组织，而不是按“原生接口 / 自定义接口”划分。这一点很重要，因为调用方真正关心的是“销售要调哪些接口”“采购要调哪些接口”“报表要调哪些接口”。

当前网关包含这些方向：

商品搜索、商品创建、商品详情、图片上传
客户与供应商主数据
销售订单、发货、开票、收款、退货
采购订单、收货、采购发票、供应商付款、采购退货
经营总览、销售分析、采购分析、应收应付、资金流水
移动端版本信息与认证

接口返回也统一成类似这样的包络：

{
  "ok": true,
  "status": "success",
  "code": "ORDER_CREATED",
  "message": "业务提示信息",
  "data": {},
  "meta": {}
}

错误响应也做了统一错误码，例如认证、权限、资源不存在、库存不足、参数校验失败等。这个细节很容易被忽略，但对前端开发很友好：不用在每个页面里猜后端到底抛了什么异常。

采购链路里一个值得记的点

采购模块的设计文档比较完整。它把采购拆成：

创建采购订单
按实际到货生成采购收货单
按实际收货生成采购发票
供应商付款登记
采购退货

这里有一个关键设计原则：采购订单表示“预期采购”，真正库存入账以 Purchase Receipt 为准。也就是说，如果供应商实际到货数量和订单数量不一致，系统应该允许按实收数量收货和结算。

这比“采购订单一建就默认全部到货”的实现更接近真实业务。以后如果单独写采购模块，这个点值得展开讲。

测试体系

项目文档强调优先使用 HTTP 测试，而不是在宿主机里直接导入 Frappe 服务层。

原因是 HTTP 测试更接近真实调用路径，可以覆盖：

鉴权
权限
路由
响应包装
真实主数据
devcontainer 网络环境

文档中记录了多组测试：

销售与采购主链路
商品工作台与销售状态聚合
采购快捷链路
幂等、并发和不同数据重放
单位换算与库存结算回归
性能基线脚本

这部分我觉得很值得继续保留。很多项目写到后面乱，不只是代码问题，也是缺少一套能确认“这次改动没有把主链路弄坏”的方法。

接下来想补什么

这篇先把轮廓记下来。后面更值得写的是这些具体问题：

Frappe / ERPNext 自定义业务网关设计
采购链路如何处理“订单数量”和“实际到货”的差异
移动端如何对接 ERPNext 业务接口
商品图片上传、临时文件绑定和清理策略
HTTP 测试如何覆盖 ERPNext 自定义接口

目前最应该补的，是截图和一条完整业务链路的可视化流程图。只有文字会有点干，等把图补上，这个项目才会更像一篇可以回看的博客文章。

这个博客是怎么搭起来的

Wed, 20 May 2026 00:00:00 GMT

这个站点现在还很早期，但总算从“想弄个博客”变成了“已经有地方可以写东西”。

我对它的期待不是一次性做成一个很完整的网站，而是先把结构搭出来，然后边写边改。技术文章、项目记录、学习笔记、代码片段，还有一些动画、音乐、视频相关的小实验，都可以慢慢往里放。

为什么选这套

第一版选的是 Astro + Fuwari。

Astro 适合内容型站点。默认静态生成，部署简单，后面如果想加一些交互组件，也不用把整个博客变成一个复杂的前端应用。

Fuwari 则省掉了很多博客基础设施：

首页文章流
文章详情
归档
分类和标签
搜索
深色模式
页面转场
RSS 和 sitemap

这些东西自己从零写当然也能做，但博客的第一目标还是写内容。先用一个成熟主题把底座搭好，会更容易进入“开始写”的状态。

现在怎么部署

当前部署链路是：

本地开发
  -> git push
  -> GitHub 仓库
  -> Cloudflare Workers 构建部署
  -> blog.rgcdev.top

同时保留 GitHub Pages：

GitHub Actions
  -> pnpm build
  -> dist
  -> r-gc.github.io

这样做的好处是：主站可以走 Cloudflare，自定义域名和后续 R2 / Workers 能力都在一个体系里；GitHub Pages 则作为备用访问和对照环境。

先把栏目放出来

现在先放了几个顶层栏目：

首页：最新文章
归档：按时间、分类、标签浏览
项目：记录做过、正在做、还想继续整理的东西
笔记：保存短内容、配置备忘和学习记录
实验室：放动画、音乐、视频和交互 demo
关于：个人介绍和站点说明

项目页目前是数据驱动的，项目数据统一放在 src/data/projects.ts。这不是为了炫技，只是为了以后新增项目时不用每次都改页面结构。

第一版先到这里

第一版已经完成：

站点初始化
中文配置
Cloudflare Workers 部署
GitHub Pages 备用部署
自定义域名
项目、笔记、实验室栏目
项目页数据化
第一批项目复盘文章

后面会慢慢补：

替换头像和 favicon
补真实项目截图
为重点项目建立详情页
优化首页布局
增加音乐和视频实验
把大图和媒体资源迁移到 Cloudflare R2

现在最重要的不是把页面一次性做漂亮，而是开始积累内容。样式、结构、动画和媒体能力都可以跟着内容慢慢长出来。

这个博客的笔记结构

Wed, 20 May 2026 00:00:00 GMT

这个博客会以笔记为主，所以先把笔记的结构定下来。

第一版不打算做得太复杂。Fuwari 本身已经有文章、归档、标签、分类、搜索和 RSS。与其重新做一套知识库系统，不如先复用它的文章模型，再用一点约定把内容组织清楚。

分类只回答一件事

category 只用来说明这篇内容属于哪种大类：

笔记
项目
博客
实验
随笔

这样分类不会越来越碎。比如一篇 Cloudflare Workers 部署记录，它的分类是“笔记”，而不是“Cloudflare”。

标签负责具体主题

tags 用来描述具体内容和用途：

Cloudflare
Workers
部署
排错
Frappe
Docker
速查

以后想按技术栈、问题类型或者使用场景找内容，都可以靠标签。

笔记类型

当前先按这些类型整理：

速查：命令、参数、步骤和常用片段
排错：报错原因、排查路径和最后的修复方法
配置：环境、工具链、部署和服务配置
学习：读文档、看源码、学框架时留下的理解
项目笔记：项目推进过程里的设计、接口、测试和取舍
阅读摘记：文章、文档、书和资料里值得回看的内容
实验记录：动画、音乐、视频和交互效果的试验过程

这些类型目前先作为标签使用。等内容多起来之后，再决定要不要单独做成更强的字段。

写作原则

笔记不追求一次写成完美文章。

对这个博客来说，更重要的是先把有用的信息放下来：当时的问题是什么，怎么查的，最后怎么解决，以及下次遇到时应该从哪里开始。

如果一篇短笔记后来变得很重要，再把它扩展成完整文章也不迟。

Cloudflare Workers 部署博客的记录

Wed, 20 May 2026 00:00:00 GMT

这个博客目前主部署放在 Cloudflare Workers，GitHub Pages 作为备用。

当前 Cloudflare 侧的构建命令是：

pnpm run build

部署命令是：

npx wrangler deploy

项目里保留了 wrangler.jsonc，核心配置是把 Astro 构建后的 dist 作为静态资源目录：

{
  "name": "r-gc-github-io",
  "compatibility_date": "2026-05-20",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash"
  }
}

后续如果接入 R2 放图片、音频或视频，Workers 会比单纯 GitHub Pages 更方便一些。现在先保持静态博客形态，等媒体资源真的多起来再迁移。

Git 代理配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Git 代理相关命令。

查看当前 Git 代理

git config --global --get http.proxy
git config --global --get https.proxy
git config --show-origin --get http.proxy
git config --show-origin --get https.proxy

查看所有代理相关配置：

git config --global --list | grep -i proxy

设置 HTTP/HTTPS 代理

HTTP 代理：

git config --global http.proxy http://127.0.0.1:10808
git config --global https.proxy http://127.0.0.1:10808

SOCKS5 代理：

git config --global http.proxy socks5://127.0.0.1:10808
git config --global https.proxy socks5://127.0.0.1:10808

如果代理软件同时提供 HTTP 和 SOCKS5 端口，Git 的 HTTP/HTTPS 拉取通常用 HTTP 代理更直接。

只给 GitHub 设置代理

git config --global http.https://github.com.proxy http://127.0.0.1:10808

取消 GitHub 单独代理：

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

这种写法只影响访问 https://github.com 的 Git HTTP 请求。

取消全局代理

git config --global --unset http.proxy
git config --global --unset https.proxy

如果不确定是否存在：

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

临时使用代理执行一次 Git 命令

git -c http.proxy=http://127.0.0.1:10808 -c https.proxy=http://127.0.0.1:10808 pull

这个不会写入配置文件，只对这一次命令生效。

注意 SSH remote 不走 Git HTTP 代理

如果 remote 是 HTTPS：

https://github.com/USER/REPO.git

Git 的 http.proxy / https.proxy 会生效。

如果 remote 是 SSH：

git@github.com:USER/REPO.git

Git 的 HTTP 代理不会生效，需要配置 SSH 代理，也就是 ~/.ssh/config 里的 ProxyCommand。

常用参数解释

http.proxy：Git 访问 HTTP 地址时使用的代理。

https.proxy：Git 访问 HTTPS 地址时使用的代理。

http.https://github.com.proxy：只给指定 URL 前缀设置代理。

--get：只读取某个配置值。

--unset：删除某个配置值。

--unset-all：删除同名配置的所有值。

-c key=value：只在当前这次 Git 命令里临时覆盖配置。

SSH 密钥生成与 GitHub 配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 SSH key 相关命令。

生成 ed25519 key

ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_github

如果是给另一个 GitHub 账号单独生成 key，可以换文件名：

ssh-keygen -t ed25519 -C "blog@example.com" -f ~/.ssh/id_ed25519_r_gc

查看公钥

cat ~/.ssh/id_ed25519_github.pub

把输出内容复制到 GitHub：

GitHub -> Settings -> SSH and GPG keys -> New SSH key

注意复制的是 .pub 公钥，不是没有后缀的私钥。

公钥放到目标服务器

原则很简单：

私钥留在访问方
公钥放到被访问方

比如从自己的电脑访问一台 Linux 服务器，就在自己的电脑生成 key，然后把 .pub 公钥放到目标服务器对应用户的：

~/.ssh/authorized_keys

如果目标登录用户是 deploy：

/home/deploy/.ssh/authorized_keys

如果目标登录用户是 root：

/root/.ssh/authorized_keys

快捷添加公钥

本机执行：

ssh-copy-id -i ~/.ssh/id_ed25519_github.pub user@server_ip

指定 SSH 端口：

ssh-copy-id -i ~/.ssh/id_ed25519_github.pub -p 2222 user@server_ip

它会自动把公钥追加到目标服务器的：

~/.ssh/authorized_keys

第一次执行通常需要输入目标服务器用户密码，因为此时目标服务器还没有你的公钥，只能先用密码登录一次。

成功后测试：

ssh user@server_ip

如果你的私钥设置了 passphrase，后续登录时可能还会输入私钥密码。这个不是服务器用户密码。

如果服务器已经禁用了密码登录：

PasswordAuthentication no

那么 ssh-copy-id 也无法用密码进去。此时只能通过云厂商控制台、已有可登录账号、服务器面板，或者让管理员帮你把公钥放进去。

已登录服务器后手动添加

如果你已经登录到了目标服务器，可以直接在服务器上追加公钥。

先在本机查看并复制公钥：

cat ~/.ssh/id_ed25519_github.pub

复制整行内容，格式类似：

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@example.com

然后在目标服务器上执行：

mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat >> ~/.ssh/authorized_keys

粘贴刚才复制的公钥整行，回车，然后按 Ctrl + D 结束输入。

最后设置权限：

chmod 600 ~/.ssh/authorized_keys

也可以用 echo 一行追加：

mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@example.com' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

注意使用 >>，不要随手用 >：

>> 追加，不会删除原有 key
>  覆盖，会清空 authorized_keys 里的原有 key

如果确定要重建整个 authorized_keys，才使用：

echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... you@example.com' > ~/.ssh/authorized_keys

设置权限

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519_github
chmod 644 ~/.ssh/id_ed25519_github.pub

如果权限太开放，SSH 可能会拒绝使用私钥。

启动 ssh-agent 并添加 key

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_github

查看 agent 里已有 key：

ssh-add -l

从 agent 删除某个 key：

ssh-add -d ~/.ssh/id_ed25519_github

清空 agent 中所有 key：

ssh-add -D

测试 GitHub SSH

普通测试：

ssh -T git@github.com

如果 ~/.ssh/config 里配置了 Host 别名：

ssh -T git@github-r-gc

成功时通常会看到类似：

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

常用参数解释

ssh-keygen：生成 SSH 密钥。

-t ed25519：指定密钥算法。现在一般优先用 ed25519。

-C "you@example.com"：给 key 加注释，常用邮箱或用途，方便以后识别。

-f ~/.ssh/id_ed25519_github：指定生成文件路径和文件名。

.pub：公钥文件，可以上传到 GitHub。

没有 .pub 后缀的文件：私钥文件，不能公开。

ssh-agent：本地密钥代理，可以记住已添加的私钥。

ssh-add：把私钥加入 agent。

ssh -T：测试 SSH 认证，不打开远程 shell。

authorized_keys：目标服务器上保存允许登录的公钥列表。

ssh-copy-id：把本机公钥复制到目标服务器 authorized_keys 的快捷命令。

>>：追加内容到文件末尾，适合给 authorized_keys 增加新公钥。

>：覆盖文件内容，可能删除已有公钥，谨慎使用。

SSH 代理与多 GitHub 账号配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 SSH 代理和多账号配置。

基础 GitHub SSH 配置

编辑：

nano ~/.ssh/config

普通 GitHub SSH：

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

GitHub SSH 走 443 端口

有些网络环境下，22 端口不稳定，可以改用 GitHub 提供的 SSH over HTTPS 端口：

Host github.com
  HostName ssh.github.com
  User git
  Port 443
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

测试：

ssh -T git@github.com

SSH 通过 SOCKS5 代理（本地代理环境推荐）

Host github.com
  HostName ssh.github.com
  User git
  Port 443
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes
  ProxyCommand nc -X 5 -x 127.0.0.1:10808 %h %p

这里适合本地代理监听在 127.0.0.1:10808 的情况。

多 GitHub 账号 Host 别名

默认账号：

Host github.com
  HostName ssh.github.com
  User git
  Port 443
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes
  ProxyCommand nc -X 5 -x 127.0.0.1:10808 %h %p

博客账号：

Host github-r-gc
  HostName ssh.github.com
  User git
  Port 443
  IdentityFile ~/.ssh/id_ed25519_r_gc
  IdentitiesOnly yes
  ProxyCommand nc -X 5 -x 127.0.0.1:10808 %h %p

使用别名测试：

ssh -T git@github-r-gc

仓库 remote 使用别名：

git remote set-url origin git@github-r-gc:r-gc/r-gc.github.io.git

这样默认 github.com 可以继续给主力账号使用，github-r-gc 专门给博客账号使用。

查看 SSH 实际使用的配置

ssh -G github.com | less
ssh -G github-r-gc | less

调试连接过程：

ssh -vT git@github.com
ssh -vT git@github-r-gc

如果信息不够，再增加 v：

ssh -vvvT git@github.com

常用参数解释

Host：本地别名。Git remote 里写的主机名会匹配它。

HostName：真实连接的服务器地址。

User git：GitHub SSH 固定使用 git 用户。

Port 443：使用 443 端口连接 GitHub SSH，适合 22 端口不通或不稳定时。

IdentityFile：指定私钥路径。

IdentitiesOnly yes：只使用 IdentityFile 指定的 key，避免 SSH 尝试一堆其它 key。

ProxyCommand：连接目标服务器前，先通过这个命令建立网络通道。

nc：netcat，用来建立代理连接。

-X 5：告诉 nc 使用 SOCKS5 代理。

-x 127.0.0.1:10808：指定代理地址和端口。

%h：SSH 会替换成目标主机，也就是 HostName。

%p：SSH 会替换成目标端口，也就是 Port。

Git 多账号配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Git 账号相关命令。

查看当前配置

git config --list
git config --global --list
git config --local --list
git config --show-origin --list

--show-origin 会显示配置来自哪个文件，排查“为什么这个仓库用错账号”时很有用。

设置全局账号

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

全局配置会写入：

~/.gitconfig

适合主力账号。比如一台机器主要用 rgc318 工作，就把全局账号设成 rgc318 对应的用户名和邮箱。

设置当前仓库账号

在仓库目录里执行：

git config user.name "Blog Account"
git config user.email "blog@example.com"

这会写入当前仓库的：

.git/config

适合某个仓库需要使用另一个身份的情况。

查看某个配置最终生效值

git config user.name
git config user.email
git config --show-origin user.name
git config --show-origin user.email

Git 配置优先级大致是：

仓库 local > 用户 global > 系统 system

所以仓库里设置过 user.name，就会覆盖全局配置。

修改远程仓库地址

查看远程地址：

git remote -v

改成普通 GitHub SSH 地址：

git remote set-url origin git@github.com:USER/REPO.git

改成 HTTPS 地址：

git remote set-url origin https://github.com/USER/REPO.git

改成 SSH Host 别名地址：

git remote set-url origin git@github-r-gc:r-gc/r-gc.github.io.git

这里的 github-r-gc 不是 GitHub 官方域名，而是 ~/.ssh/config 里自己定义的 Host 别名。

单仓库指定 SSH key

在仓库目录里执行：

git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_r_gc -o IdentitiesOnly=yes"

查看是否生效：

git config --local core.sshCommand

取消：

git config --unset core.sshCommand

这个方式适合“默认 GitHub 账号保持主力账号，但某个仓库固定使用另一把 key”。

常用参数解释

--global：写入当前用户的全局 Git 配置。

--local：只看或只改当前仓库配置。默认在仓库中执行 git config 时就是 local。

--show-origin：显示配置来源文件，排查配置覆盖时常用。

remote set-url：修改已有 remote 的 URL，不会重建 remote。

core.sshCommand：让当前仓库执行 Git SSH 操作时使用指定 SSH 命令。

-i ~/.ssh/id_ed25519_r_gc：指定 SSH 私钥文件。

-o IdentitiesOnly=yes：只使用显式指定的 key，避免 SSH 把其它 key 也拿去尝试。

终端代理与 curl / wget 配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制终端代理相关命令。

临时设置终端代理

HTTP 代理：

export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
export HTTP_PROXY=http://127.0.0.1:10808
export HTTPS_PROXY=http://127.0.0.1:10808

SOCKS5 代理：

export all_proxy=socks5://127.0.0.1:10808
export ALL_PROXY=socks5://127.0.0.1:10808

常见组合：

export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
export all_proxy=socks5://127.0.0.1:10808

这些只对当前终端会话生效。新开终端后需要重新设置。

取消终端代理

unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset all_proxy
unset ALL_PROXY

查看当前代理环境变量

env | grep -i proxy

或者：

echo "$http_proxy"
echo "$https_proxy"
echo "$all_proxy"

设置不走代理的地址

export no_proxy=localhost,127.0.0.1,::1
export NO_PROXY=localhost,127.0.0.1,::1

如果要让局域网地址也不走代理：

export no_proxy=localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8

单次命令使用代理

http_proxy=http://127.0.0.1:10808 https_proxy=http://127.0.0.1:10808 curl https://github.com

不污染当前终端，适合临时测试。

curl 使用代理

HTTP 代理：

curl -x http://127.0.0.1:10808 https://github.com

SOCKS5 代理：

curl -x socks5://127.0.0.1:10808 https://github.com

让 DNS 也通过 SOCKS5 代理解析：

curl -x socks5h://127.0.0.1:10808 https://github.com

查看连接细节：

curl -v -x http://127.0.0.1:10808 https://github.com

只看响应头：

curl -I -x http://127.0.0.1:10808 https://github.com

wget 使用代理

单次命令：

wget -e use_proxy=yes -e http_proxy=http://127.0.0.1:10808 -e https_proxy=http://127.0.0.1:10808 https://github.com

写入用户配置：

nano ~/.wgetrc

use_proxy = on
http_proxy = http://127.0.0.1:10808
https_proxy = http://127.0.0.1:10808

常用参数解释

http_proxy：HTTP 请求使用的代理。

https_proxy：HTTPS 请求使用的代理。

all_proxy：所有协议的通用代理，常用于 SOCKS5。

no_proxy：不走代理的主机或地址。

curl -x：给当前 curl 请求指定代理。

socks5://：使用 SOCKS5 代理，但 DNS 可能仍在本地解析。

socks5h://：使用 SOCKS5 代理，并让代理端解析 DNS。

curl -v：输出详细连接过程。

curl -I：只请求响应头。

wget -e：临时设置 wget 配置项。

npm / pnpm / yarn 代理与镜像配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Node 包管理器相关配置。

npm 查看配置

npm config list
npm config get proxy
npm config get https-proxy
npm config get registry

npm 设置代理

npm config set proxy http://127.0.0.1:10808
npm config set https-proxy http://127.0.0.1:10808

取消代理：

npm config delete proxy
npm config delete https-proxy

npm 设置 registry

官方源：

npm config set registry https://registry.npmjs.org/

国内镜像：

npm config set registry https://registry.npmmirror.com/

查看：

npm config get registry

pnpm 查看配置

pnpm config list
pnpm config get proxy
pnpm config get https-proxy
pnpm config get registry

pnpm 设置代理

pnpm config set proxy http://127.0.0.1:10808
pnpm config set https-proxy http://127.0.0.1:10808

取消代理：

pnpm config delete proxy
pnpm config delete https-proxy

pnpm 设置 registry

官方源：

pnpm config set registry https://registry.npmjs.org/

国内镜像：

pnpm config set registry https://registry.npmmirror.com/

查看：

pnpm config get registry

yarn 查看与设置

查看：

yarn config get proxy
yarn config get https-proxy
yarn config get registry

设置代理：

yarn config set proxy http://127.0.0.1:10808
yarn config set https-proxy http://127.0.0.1:10808

取消代理：

yarn config delete proxy
yarn config delete https-proxy

设置 registry：

yarn config set registry https://registry.npmjs.org/

使用环境变量临时代理

http_proxy=http://127.0.0.1:10808 https_proxy=http://127.0.0.1:10808 pnpm install

或者：

HTTP_PROXY=http://127.0.0.1:10808 HTTPS_PROXY=http://127.0.0.1:10808 npm install

常用配置文件位置

npm 用户配置通常在：

~/.npmrc

pnpm 也会读取 npm 兼容配置。可以直接查看：

cat ~/.npmrc

常用参数解释

proxy：HTTP 请求代理。

https-proxy：HTTPS 请求代理。

registry：包下载源地址。

config set：写入配置。

config get：读取配置。

config delete：删除配置。

registry.npmjs.org：npm 官方源。

registry.npmmirror.com：常用 npm 国内镜像源。

pip / apt / Docker 代理配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 pip、apt 和 Docker 代理配置。

pip 临时使用代理

pip install requests --proxy http://127.0.0.1:10808

指定源：

pip install requests -i https://pypi.org/simple

指定国内镜像：

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

pip 写入用户配置

pip config set global.proxy http://127.0.0.1:10808
pip config set global.index-url https://pypi.org/simple

查看配置：

pip config list
pip config debug

取消配置：

pip config unset global.proxy
pip config unset global.index-url

常见用户配置文件位置：

~/.config/pip/pip.conf

apt 临时使用代理

sudo apt -o Acquire::http::Proxy="http://127.0.0.1:10808" update

同时设置 HTTP 和 HTTPS：

sudo apt \
  -o Acquire::http::Proxy="http://127.0.0.1:10808" \
  -o Acquire::https::Proxy="http://127.0.0.1:10808" \
  update

apt 写入代理配置

创建配置文件：

sudo nano /etc/apt/apt.conf.d/95proxies

写入：

Acquire::http::Proxy "http://127.0.0.1:10808";
Acquire::https::Proxy "http://127.0.0.1:10808";

取消：

sudo rm /etc/apt/apt.conf.d/95proxies

如果代理在 Windows 主机上，WSL 里 127.0.0.1 是否可用取决于网络模式和代理软件监听地址；不通时可以改用 Windows 主机 IP。

Docker CLI 代理

创建 Docker 客户端配置目录：

mkdir -p ~/.docker

编辑：

nano ~/.docker/config.json

写入：

{
  "proxies": {
    "default": {
      "httpProxy": "http://127.0.0.1:10808",
      "httpsProxy": "http://127.0.0.1:10808",
      "noProxy": "localhost,127.0.0.1,::1"
    }
  }
}

这个配置主要影响 Docker 客户端给容器传递的代理环境。

Docker daemon 代理

创建 systemd drop-in 目录：

sudo mkdir -p /etc/systemd/system/docker.service.d

编辑：

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

写入：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:10808"
Environment="HTTPS_PROXY=http://127.0.0.1:10808"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

重载并重启 Docker：

sudo systemctl daemon-reload
sudo systemctl restart docker

查看 Docker 服务环境变量：

sudo systemctl show --property=Environment docker

取消 Docker daemon 代理：

sudo rm /etc/systemd/system/docker.service.d/http-proxy.conf
sudo systemctl daemon-reload
sudo systemctl restart docker

常用参数解释

pip --proxy：只给当前 pip 命令指定代理。

pip config set global.proxy：写入 pip 用户配置。

pip config debug：显示 pip 会读取哪些配置文件。

apt -o：只给当前 apt 命令临时覆盖配置。

Acquire::http::Proxy：apt 的 HTTP 代理配置。

Acquire::https::Proxy：apt 的 HTTPS 代理配置。

~/.docker/config.json：Docker CLI 用户配置。

docker.service.d：systemd 用来覆盖 Docker 服务配置的目录。

systemctl daemon-reload：重新加载 systemd 配置。

systemctl restart docker：重启 Docker 服务，让代理配置生效。

Linux CPU / 内存 / 磁盘状态检查速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Linux 系统状态检查命令。

系统整体状态

uptime

查看系统运行时间、登录用户数和负载。

top

交互式查看 CPU、内存和进程。

htop

更好用的 top，如果没有需要先安装。

CPU 信息

lscpu

查看 CPU 型号、核心数、线程数、架构等信息。

nproc

查看可用 CPU 核心数。

cat /proc/cpuinfo | grep "model name" | head

查看 CPU 型号。

CPU 使用率

top

进入后常用按键：

P：按 CPU 使用率排序
M：按内存使用率排序
q：退出

如果安装了 sysstat：

mpstat 1

每 1 秒刷新一次 CPU 使用情况。

内存状态

free -h

人类可读格式查看内存。

free -m

以 MB 为单位查看内存。

cat /proc/meminfo | head

查看更详细的内存信息。

磁盘空间

df -h

查看各挂载点磁盘使用情况。

df -Th

同时显示文件系统类型。

du -sh .

查看当前目录总大小。

du -h --max-depth=1

du -h --max-depth=1 | sort -h

按大小排序。

磁盘 IO

如果安装了 sysstat：

iostat -xz 1

每 1 秒刷新磁盘 IO 状态。

如果安装了 iotop：

sudo iotop

查看哪个进程正在读写磁盘。

进程查看

ps aux

查看所有进程。

ps aux | grep nginx

按关键词查进程。

pgrep -af nginx

更简洁地按进程名查找。

杀进程

kill PID

正常结束进程。

kill -9 PID

强制结束进程。优先用普通 kill，不行再用 -9。

查看端口占用进程

sudo lsof -i :8080

或者：

sudo ss -lntp | grep :8080

常用参数解释

-h：human readable，人类可读格式，例如 GB / MB。

-T：显示文件系统类型。

--max-depth=1：只统计当前目录下一层。

sort -h：按人类可读大小排序。

ps aux：显示所有用户的所有进程。

grep：按文本过滤。

kill -9：发送 SIGKILL，强制结束进程。

Linux 网络状态检查速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制网络状态检查命令。

查看 IP 地址

ip addr

简写：

ip a

只看 IPv4：

ip -4 addr

查看默认路由

ip route

查看默认网关：

ip route | grep default

查看监听端口

ss -lntp

查看 TCP 监听端口和进程。

ss -lnup

查看 UDP 监听端口和进程。

查看某个端口：

sudo ss -lntp | grep :8080

查看连接状态

ss -ant

查看所有 TCP 连接。

ss -ant | grep ESTAB

查看已建立连接。

ss -ant | grep TIME-WAIT | wc -l

统计 TIME-WAIT 数量。

查看端口占用

sudo lsof -i :8080

或者：

sudo fuser -v 8080/tcp

测试连通性

ping github.com

指定次数：

ping -c 4 github.com

测试 TCP 端口：

nc -vz github.com 443

测试 HTTP：

curl -I https://github.com

显示详细连接过程：

curl -v https://github.com

DNS 检查

nslookup github.com

如果有 dig：

dig github.com

只看 A 记录：

dig github.com A +short

指定 DNS 服务器：

dig @1.1.1.1 github.com
dig @8.8.8.8 github.com

查看 DNS 配置

cat /etc/resolv.conf

如果使用 systemd-resolved：

resolvectl status

路由追踪

traceroute github.com

如果没有 traceroute，可以用：

tracepath github.com

查看公网 IP

curl ifconfig.me

或者：

curl https://api.ipify.org

常用参数解释

ss：查看 socket 状态，现代 Linux 上常用来替代 netstat。

-l：只显示监听中的端口。

-n：不解析域名和服务名，显示数字端口。

-t：TCP。

-u：UDP。

-p：显示进程信息，通常需要 sudo。

nc -vz：测试 TCP 端口是否可连接。

curl -I：只请求响应头。

curl -v：输出详细连接过程。

dig +short：只输出简短解析结果。

Docker 容器不退出与调试命令速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Docker 容器保活和调试命令。

让容器不退出

最常用：

docker run -d --name debug-container IMAGE tail -f /dev/null

或者：

docker run -d --name debug-container IMAGE sleep infinity

如果镜像里没有 sleep infinity，用：

docker run -d --name debug-container IMAGE sh -c "while true; do sleep 3600; done"

交互式进入容器

进入正在运行的容器：

docker exec -it CONTAINER bash

如果没有 bash：

docker exec -it CONTAINER sh

以 root 用户进入：

docker exec -it -u root CONTAINER bash

直接启动并进入临时容器

docker run --rm -it IMAGE bash

如果没有 bash：

docker run --rm -it IMAGE sh

挂载当前目录：

docker run --rm -it -v "$PWD":/work -w /work IMAGE bash

容器退出后查看原因

查看所有容器：

docker ps -a

查看日志：

docker logs CONTAINER

查看退出码：

docker inspect -f '{{.State.ExitCode}}' CONTAINER

查看错误信息：

docker inspect -f '{{.State.Error}}' CONTAINER

查看状态：

docker inspect -f '{{.State.Status}}' CONTAINER

重新启动已退出容器

docker start CONTAINER

启动并附加到终端：

docker start -ai CONTAINER

停止和删除容器

停止：

docker stop CONTAINER

删除：

docker rm CONTAINER

强制删除运行中的容器：

docker rm -f CONTAINER

常用 docker run 模板

后台运行并指定名称：

docker run -d --name app IMAGE

映射端口：

docker run -d --name app -p 8080:80 IMAGE

设置环境变量：

docker run -d --name app -e NODE_ENV=production IMAGE

挂载目录：

docker run -d --name app -v "$PWD":/app IMAGE

指定工作目录：

docker run -d --name app -w /app IMAGE

指定网络：

docker run -d --name app --network my-network IMAGE

容器退出自动删除：

docker run --rm IMAGE

Docker Compose 调试

进入服务容器：

docker compose exec SERVICE bash

如果没有 bash：

docker compose exec SERVICE sh

临时启动服务并进入：

docker compose run --rm SERVICE bash

只启动某个服务：

docker compose up -d SERVICE

重启某个服务：

docker compose restart SERVICE

常用参数解释

-d：后台运行容器。

--name：指定容器名称。

-it：交互式终端，常用于进入 shell。

--rm：容器退出后自动删除。

-v：挂载目录或 volume。

-w：指定容器内工作目录。

-p 8080:80：把宿主机 8080 映射到容器 80。

-e KEY=value：设置环境变量。

--network：指定容器加入的 Docker 网络。

tail -f /dev/null：持续等待，不主动退出，常用于调试保活。

sleep infinity：无限睡眠，让容器保持运行。

exec：在运行中的容器里执行命令。

start -ai：启动已存在容器并附加输入输出。

Docker 状态检查速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Docker 状态检查命令。

Docker 服务状态

docker version

查看客户端和服务端版本。

docker info

查看 Docker daemon 信息。

sudo systemctl status docker

查看 Docker 服务状态。

启动 Docker：

sudo systemctl start docker

重启 Docker：

sudo systemctl restart docker

设置开机启动：

sudo systemctl enable docker

查看容器

运行中的容器：

docker ps

所有容器：

docker ps -a

只显示容器 ID：

docker ps -q

格式化输出：

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

查看容器详情

docker inspect CONTAINER

查看容器 IP：

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' CONTAINER

查看容器启动命令：

docker inspect -f '{{.Path}} {{range .Args}}{{.}} {{end}}' CONTAINER

查看日志

docker logs CONTAINER

查看最后 100 行：

docker logs --tail 100 CONTAINER

实时跟随：

docker logs -f CONTAINER

带时间：

docker logs -f --timestamps CONTAINER

查看资源占用

docker stats

只看某个容器：

docker stats CONTAINER

只输出一次：

docker stats --no-stream

查看镜像

docker images

查看镜像磁盘占用：

docker system df

查看更详细占用：

docker system df -v

查看网络

docker network ls

查看网络详情：

docker network inspect NETWORK

查看某个容器连接的网络：

docker inspect -f '{{json .NetworkSettings.Networks}}' CONTAINER

查看卷

docker volume ls

查看卷详情：

docker volume inspect VOLUME

Docker Compose 状态

docker compose ps

查看日志：

docker compose logs
docker compose logs -f
docker compose logs --tail 100 SERVICE

查看配置展开结果：

docker compose config

常用参数解释

docker ps：查看运行中的容器。

-a：包含已停止容器。

-q：只输出 ID。

--format：自定义输出格式。

inspect：查看对象完整 JSON 信息。

-f：format，按模板提取字段。

logs -f：持续跟随日志输出。

--tail 100：只显示最后 100 行。

stats：查看容器 CPU、内存、网络 IO、磁盘 IO。

--no-stream：只输出一次，不持续刷新。

文件查找与文本搜索速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制文件查找和文本搜索命令。

find 查找文件

按文件名：

find . -name "*.md"

忽略大小写：

find . -iname "*readme*"

按目录深度：

find . -maxdepth 2 -type f

只找目录：

find . -type d -name "node_modules"

按大小：

find . -type f -size +100M

按修改时间：

find . -type f -mtime -1

grep 搜索文本

递归搜索：

grep -R "keyword" .

显示行号：

grep -Rni "keyword" .

排除目录：

grep -R "keyword" . --exclude-dir=node_modules

sed 常用替换

只输出匹配行附近内容：

sed -n '1,120p' file.txt

替换输出，不修改文件：

sed 's/old/new/g' file.txt

原地替换：

sed -i 's/old/new/g' file.txt

macOS 上原地替换：

sed -i '' 's/old/new/g' file.txt

awk 常用命令

打印第一列：

awk '{print $1}' file.txt

按冒号分隔：

awk -F ':' '{print $1}' /etc/passwd

打印匹配行：

awk '/keyword/ {print}' file.txt

xargs 常用组合

查找并删除日志文件：

find . -name "*.log" -print0 | xargs -0 rm

批量 grep：

find . -name "*.md" -print0 | xargs -0 grep -n "keyword"

配合 rg 文件列表：

rg --files -g "*.md" | xargs grep -n "keyword"

查看大文件

find . -type f -size +100M -print

按大小排序：

find . -type f -printf "%s %p\n" | sort -n | tail

常用参数解释

rg：ripgrep，速度快，默认尊重 .gitignore。

rg --files：列出文件。

-g "*.ts"：只包含某类路径。

-g "!node_modules"：排除路径。

find -name：按名称匹配，区分大小写。

find -iname：按名称匹配，不区分大小写。

-type f：只找文件。

-type d：只找目录。

-maxdepth：限制搜索深度。

grep -R：递归搜索。

grep -n：显示行号。

sed -n：只输出指定内容。

sed -i：原地修改文件。

awk -F：指定字段分隔符。

xargs：把前一个命令的输出变成后一个命令的参数。

-print0 和 xargs -0：用空字符分隔，能安全处理带空格的文件名。

Docker Compose 常用命令速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 Docker Compose 常用命令。

查看服务状态

docker compose ps

查看所有容器，包括已退出：

docker compose ps -a

启动服务

前台启动：

docker compose up

后台启动：

docker compose up -d

只启动某个服务：

docker compose up -d SERVICE

启动前重新构建：

docker compose up -d --build

停止服务

停止并删除容器和默认网络：

docker compose down

只停止，不删除容器：

docker compose stop

重新启动：

docker compose restart

只重启某个服务：

docker compose restart SERVICE

不删除 volume 的停止方式

docker compose down

默认不会删除 named volumes。

如果加了这个参数才会删除 volume：

docker compose down -v

所以不想删数据时，不要加 -v。

查看日志

查看全部日志：

docker compose logs

实时跟随：

docker compose logs -f

查看某个服务：

docker compose logs -f SERVICE

只看最后 100 行：

docker compose logs --tail 100 SERVICE

带时间戳：

docker compose logs -f --timestamps SERVICE

进入容器

docker compose exec SERVICE bash

如果没有 bash：

docker compose exec SERVICE sh

以 root 进入：

docker compose exec -u root SERVICE bash

临时运行一个服务命令

docker compose run --rm SERVICE bash

执行一次命令：

docker compose run --rm SERVICE npm install

构建镜像

docker compose build

不使用缓存：

docker compose build --no-cache

只构建某个服务：

docker compose build SERVICE

拉取镜像

docker compose pull

只拉某个服务：

docker compose pull SERVICE

指定 compose 文件

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

指定项目名：

docker compose -p PROJECT_NAME up -d

profiles

启动指定 profile：

docker compose --profile dev up -d

多个 profile：

docker compose --profile dev --profile debug up -d

查看最终配置

docker compose config

这个命令会展开变量、合并多个 compose 文件，排查配置时很好用。

常用参数解释

up：创建并启动服务。

-d：后台运行。

down：停止并删除容器和网络。

stop：只停止容器，不删除。

restart：重启服务。

logs -f：实时跟随日志。

exec：进入正在运行的服务容器执行命令。

run --rm：临时创建容器执行命令，结束后删除。

build --no-cache：不使用构建缓存。

-f：指定 compose 文件。

-p：指定项目名，影响容器、网络、volume 前缀。

--profile：启用带 profile 的服务。

端口占用与进程排错速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制端口和进程排错命令。

Linux 查看端口监听

sudo ss -lntp

查看指定端口：

sudo ss -lntp | grep :3000

UDP：

sudo ss -lnup

Linux 查看端口占用进程

sudo lsof -i :3000

或者：

sudo fuser -v 3000/tcp

Linux 杀掉占用端口的进程

先查 PID：

sudo lsof -i :3000

正常结束：

kill PID

强制结束：

kill -9 PID

一行命令：

sudo kill -9 $(sudo lsof -t -i :3000)

Linux 查看进程

ps aux | grep node

更简洁：

pgrep -af node

查看进程树：

pstree -ap

Windows 查看端口占用

PowerShell 或 CMD：

netstat -ano | findstr :3000

查看 PID 对应进程：

tasklist | findstr PID

杀进程：

taskkill /PID PID /F

PowerShell 写法：

Get-Process -Id PID
Stop-Process -Id PID -Force

监听地址区别

只允许本机访问：

127.0.0.1:3000

监听所有网卡：

0.0.0.0:3000

如果服务在 WSL / Docker / 虚拟机里，想让外部访问，通常需要监听 0.0.0.0，并确认端口映射或防火墙规则。

测试端口是否可连

nc -vz 127.0.0.1 3000

测试 HTTP 服务：

curl -I http://127.0.0.1:3000

查看详细连接过程：

curl -v http://127.0.0.1:3000

常用参数解释

ss -lntp：查看 TCP 监听端口和进程。

lsof -i :3000：查看使用 3000 端口的进程。

lsof -t：只输出 PID。

fuser -v 3000/tcp：查看使用指定 TCP 端口的进程。

kill：发送终止信号。

kill -9：强制终止。

netstat -ano：Windows 查看连接、监听端口和 PID。

taskkill /F：Windows 强制结束进程。

nc -vz：测试 TCP 端口连通性。

systemd 服务管理速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 systemd 服务管理命令。

查看服务状态

sudo systemctl status SERVICE

例如：

sudo systemctl status docker
sudo systemctl status nginx

启动、停止、重启

启动：

sudo systemctl start SERVICE

停止：

sudo systemctl stop SERVICE

重启：

sudo systemctl restart SERVICE

重新加载配置：

sudo systemctl reload SERVICE

如果不确定服务是否支持 reload：

sudo systemctl reload-or-restart SERVICE

开机启动

启用开机启动：

sudo systemctl enable SERVICE

禁用开机启动：

sudo systemctl disable SERVICE

立即启用并启动：

sudo systemctl enable --now SERVICE

查看是否开机启动：

systemctl is-enabled SERVICE

查看是否正在运行：

systemctl is-active SERVICE

查看日志

查看服务日志：

journalctl -u SERVICE

实时跟随：

journalctl -u SERVICE -f

看最近 100 行：

journalctl -u SERVICE -n 100

从今天开始：

journalctl -u SERVICE --since today

指定时间范围：

journalctl -u SERVICE --since "2026-05-20 10:00" --until "2026-05-20 12:00"

查看失败服务

systemctl --failed

重置 failed 状态：

sudo systemctl reset-failed

查看服务环境变量

sudo systemctl show --property=Environment SERVICE

查看完整配置：

systemctl cat SERVICE

修改服务后重载 systemd

sudo systemctl daemon-reload

修改 service 文件或 drop-in 配置后，都需要执行这个命令。

创建自定义 service

sudo nano /etc/systemd/system/myapp.service

示例：

[Unit]
Description=My App
After=network.target

[Service]
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

启用：

sudo systemctl daemon-reload
sudo systemctl enable --now myapp

查看：

sudo systemctl status myapp
journalctl -u myapp -f

drop-in 覆盖配置

创建覆盖目录：

sudo systemctl edit SERVICE

示例：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:10808"
Environment="HTTPS_PROXY=http://127.0.0.1:10808"

保存后：

sudo systemctl daemon-reload
sudo systemctl restart SERVICE

常用参数解释

systemctl status：查看服务状态和最近日志。

start：启动服务。

stop：停止服务。

restart：重启服务。

reload：重新加载配置，不一定重启进程。

enable：设置开机启动。

disable：取消开机启动。

enable --now：设置开机启动并立即启动。

journalctl -u：查看某个服务日志。

-f：实时跟随日志。

-n 100：显示最近 100 行。

daemon-reload：重新加载 systemd 单元文件。

Restart=always：服务退出后自动重启。

WantedBy=multi-user.target：让服务进入常规多用户启动目标。

WSL 网络与代理配置速查

Wed, 20 May 2026 00:00:00 GMT

这篇用来复制 WSL 网络和代理相关命令。

查看 WSL 版本

在 Windows PowerShell 执行：

wsl --list --verbose

简写：

wsl -l -v

关闭并重启 WSL

在 Windows PowerShell 执行：

wsl --shutdown

然后重新打开 WSL 终端。

查看 WSL 内 IP

在 WSL 执行：

hostname -I

或者：

ip addr

WSL 获取 Windows 主机 IP

常用方式：

cat /etc/resolv.conf | grep nameserver

提取 IP：

export WINDOWS_HOST=$(cat /etc/resolv.conf | awk '/nameserver/ {print $2; exit}')
echo "$WINDOWS_HOST"

WSL 使用 Windows 代理

如果 Windows 代理监听在 127.0.0.1:10808，WSL 里不一定能直接访问这个地址。更稳的方式是使用 Windows 主机 IP：

export WINDOWS_HOST=$(cat /etc/resolv.conf | awk '/nameserver/ {print $2; exit}')
export http_proxy=http://$WINDOWS_HOST:10808
export https_proxy=http://$WINDOWS_HOST:10808
export all_proxy=socks5://$WINDOWS_HOST:10808

测试：

curl -I https://github.com

取消：

unset http_proxy
unset https_proxy
unset all_proxy

Windows 访问 WSL 服务

在 WSL 启动服务时，尽量监听：

0.0.0.0

而不是只监听：

127.0.0.1

查看 WSL 服务监听：

ss -lntp

如果服务监听 0.0.0.0:3000，Windows 通常可以访问：

http://localhost:3000

查看 Windows 到 WSL 的端口

在 Windows PowerShell 中：

netstat -ano | findstr :3000

DNS 异常检查

cat /etc/resolv.conf
nslookup github.com

如果 DNS 临时异常，可以先重启 WSL：

wsl --shutdown

.wslconfig 位置

Windows 用户目录：

C:\Users\<你的用户名>\.wslconfig

常见示例：

[wsl2]
memory=8GB
processors=4
swap=8GB
localhostForwarding=true

修改后需要：

wsl --shutdown

常用参数解释

wsl -l -v：查看发行版、运行状态和 WSL 版本。

wsl --shutdown：关闭所有 WSL 实例。

hostname -I：输出当前 Linux 环境的 IP。

/etc/resolv.conf：DNS 配置文件，WSL 中常能看到 Windows 主机相关地址。

0.0.0.0：监听所有网卡，方便从 Windows 或局域网访问。

127.0.0.1：只监听本机回环地址。

localhostForwarding：WSL2 的 localhost 转发配置。

Fuwari 写作规则与 Markdown 扩展速查

Wed, 20 May 2026 00:00:00 GMT

这篇整理当前博客写文章时最容易忘的规则。

文章放哪里

正式文章放在：

src/content/posts/

笔记建议放在：

src/content/posts/notes/

可以用子目录组织文章和图片：

src/content/posts/notes/example-note/
  index.md
  cover.png
  screenshot.png

文章 frontmatter 模板

---
title: 笔记标题
published: 2026-05-20
updated: 2026-05-20
description: 一句话说明这篇笔记解决什么问题。
tags: [Linux, Docker, 速查]
category: 笔记
draft: false
---

常用字段

title：文章标题。

published：发布时间。

updated：更新时间，可选。

description：首页、归档和搜索里会显示的摘要。

tags：标签，用来描述主题和用途。

category：一级分类。当前建议只用 笔记、项目、博客、实验、随笔。

draft：是否草稿。true 时生产环境不会显示。

image：封面图，可选。

图片路径规则

网络图片：

image: https://example.com/cover.png

public 目录下的图片：

image: /images/cover.png

相对文章文件的图片：

image: ./cover.png

如果文章是目录形式：

my-note/
  index.md
  cover.png

那么 ./cover.png 会相对 index.md 生效。

创建新文章

pnpm new-post filename

也可以直接手动新建 .md 文件。手动建更适合现在这种按目录分类的笔记库。

提示块语法

普通提示：

::::note
这里是一条 note。
::::

提示：

::::tip
这里是一条 tip。
::::

警告：

::::warning
这里是一条 warning。
::::

注意：

::::caution
这里是一条 caution。
::::

重要：

::::important
这里是一条 important。
::::

自定义标题：

::::note[自定义标题]
这里是内容。
::::

GitHub 仓库卡片

::github{repo="r-gc/r-gc.github.io"}

或者：

::github{repo="rgc318/frappe_docker"}

这个卡片会在页面加载时请求 GitHub API 获取仓库信息，所以网络环境不稳定时可能加载慢。

代码块

普通代码块：

```bash
pnpm build
```

带文件名或标题的代码块可以继续使用 Expressive Code 支持的写法。这个项目已经接入了代码复制按钮、行号和语言标识。

写作注意事项

笔记不需要一开始写成完整文章。

速查类内容优先写可复制命令，再写参数解释。

排错类内容优先写现象、原因、解决命令和下次怎么判断。

项目类内容优先写为什么这样做、踩过什么坑、以后怎么复用。

RGC Blog 构建与部署注意事项

Wed, 20 May 2026 00:00:00 GMT

这篇记录当前博客项目自己的构建和部署注意事项。

本地开发命令

安装依赖：

pnpm install

启动开发服务器：

pnpm dev

本地构建：

pnpm build

预览构建结果：

pnpm preview

包管理器版本

项目指定：

{
  "packageManager": "pnpm@9.14.4"
}

并且有 preinstall 限制：

{
  "preinstall": "npx only-allow pnpm"
}

所以这个项目应该使用 pnpm，不要用 npm install 或 yarn install。

Node 版本

GitHub Actions 使用：

node-version: 22

本地如果有多个 Node 版本，优先使用 Node 22。

查看：

node -v
pnpm -v

构建命令实际做了什么

package.json 里：

{
  "build": "astro build && pagefind --site dist"
}

也就是说 pnpm build 会先生成 Astro 静态站点，再为 dist 生成 Pagefind 搜索索引。

如果只运行 astro build，页面可以生成，但搜索索引可能不是最新的。

GitHub Pages 部署方式

当前正确方式是 GitHub Actions。

workflow 文件：

.github/workflows/deploy.yml

关键步骤：

- run: pnpm install --frozen-lockfile
- run: pnpm build
- uses: actions/upload-pages-artifact@v3
- uses: actions/deploy-pages@v4

GitHub 仓库设置里应该选择：

Settings -> Pages -> Build and deployment -> Source -> GitHub Actions

不要选择：

Deploy from a branch

否则 GitHub 可能会同时触发默认 Jekyll 构建，出现一个成功的 Astro workflow 和一个失败的 pages build and deployment。

GitHub Pages 出现 Jekyll 日志是什么意思

如果日志里出现：

GitHub Pages: jekyll
Theme: jekyll-theme-primer
Source: /github/workspace/.
Destination: /github/workspace/./_site

说明 GitHub 正在把仓库根目录当成 Jekyll 站点构建。

这个项目是 Astro，不应该走 Jekyll。

解决方法是把 Pages Source 改成：

GitHub Actions

Cloudflare Workers 部署

当前 Cloudflare Workers Static Assets 配置在：

wrangler.jsonc

核心配置：

{
  "name": "r-gc-github-io",
  "compatibility_date": "2026-05-20",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash"
  }
}

Cloudflare 构建命令：

pnpm run build

部署命令：

npx wrangler deploy

站点地址配置

Astro 配置里：

site: "https://r-gc.github.io/",
base: "/",
trailingSlash: "always",

site 会影响 sitemap、RSS 等生成结果。

如果以后主域名完全切到：

https://blog.rgcdev.top/

可以考虑把 site 改成主域名。

常见排查命令

本地构建：

pnpm build

检查生成页面：

find dist -maxdepth 3 -type f | sort

查看 GitHub Actions 配置：

sed -n '1,220p' .github/workflows/deploy.yml

查看 Cloudflare 配置：

sed -n '1,160p' wrangler.jsonc

查看 scripts：

node -p "require('./package.json').scripts"

注意事项

Cloudflare Workers 和 GitHub Pages 是两套部署。

Cloudflare 当前是主站部署，GitHub Pages 可以作为备用和对照。

GitHub Pages 默认 Jekyll 构建失败，不代表 Astro workflow 失败；看绿色的 Deploy to GitHub Pages workflow 是否成功更关键。

新增笔记后，Pagefind 会在构建时更新搜索索引。

myapp HTTP 测试与回归注意事项

Wed, 20 May 2026 00:00:00 GMT

这篇从 apps/myapp/TESTING.zh-CN.md 和 README 整理。

核心原则

对 myapp.api.gateway.* 这类对外接口，优先用 HTTP 测试，而不是在 WSL 宿主机里直接导入 Frappe 服务层。

原因：

更接近前端和移动端真实调用路径
能覆盖鉴权、权限、路由、响应包装和站点上下文
更容易暴露 devcontainer、站点权限和真实主数据问题

测试环境文件

复制示例：

cp apps/myapp/.env.http-test.example apps/myapp/.env.http-test

常用配置：

MYAPP_HTTP_BASE_URL=http://localhost:8080
MYAPP_HTTP_USERNAME=Administrator
MYAPP_HTTP_PASSWORD=<password>
MYAPP_HTTP_API_KEY=<api-key>
MYAPP_HTTP_API_SECRET=<api-secret>
MYAPP_HTTP_BEARER_TOKEN=<jwt-token>
MYAPP_HTTP_PRINT_RESPONSES=1
MYAPP_HTTP_SAVE_RESPONSES=1

宿主机执行时：

MYAPP_HTTP_BASE_URL=http://localhost:8080

backend 容器内直接执行时：

MYAPP_HTTP_BASE_URL=http://localhost:8000

当前约定：宿主机侧保持 http://localhost:8080，不要随意改成 127.0.0.1。

鉴权优先级

HTTP 测试鉴权优先级：

MYAPP_HTTP_BEARER_TOKEN
MYAPP_HTTP_API_KEY / MYAPP_HTTP_API_SECRET
MYAPP_HTTP_USERNAME / MYAPP_HTTP_PASSWORD

建议：

移动端和前后端分离场景优先用 JWT Bearer Token
服务端联调用 API key / secret
用户名密码适合兼容历史流程，不建议长期依赖管理员密码

跑 HTTP 测试

销售与采购主链路：

python3 -m unittest apps.myapp.myapp.tests.http.test_gateway_http

v2 商品与销售状态聚合：

python3 -m unittest apps.myapp.myapp.tests.http.test_gateway_v2_http

采购快捷链路：

python3 -m unittest apps.myapp.myapp.tests.http.test_purchase_quick_http

跑单个测试方法：

python3 -m unittest \
  apps.myapp.myapp.tests.http.test_gateway_v2_http.GatewayV2HttpTestCase.test_create_product_and_stock_idempotent_replay

性能基线

默认采样：

python3 -m apps.myapp.myapp.tests.http.benchmark_gateway_http

指定采样次数：

python3 -m apps.myapp.myapp.tests.http.benchmark_gateway_http --samples 10

指定输出：

python3 -m apps.myapp.myapp.tests.http.benchmark_gateway_http \
  --output /tmp/myapp-perf-baseline.json

适合在这些情况下运行：

工作台查询有改动
详情聚合接口有改动
数据库索引调整后
上线前做本机基线复核
出现“接口变慢”反馈后做对比

容器内测试必须用 bench Python

如果在 backend 容器内跑单元测试，不要直接用系统 Python。

销售单位换算与库存链路

在 backend 容器中运行：

docker exec frappe_docker-backend-1 bash -lc '
  cd /home/frappe/frappe-bench &&
  env/bin/python -m unittest apps.myapp.myapp.tests.integration.test_sales_uom_stock_chain
'

重点校验：

Sales Order Item.stock_qty
Bin.actual_qty
Stock Ledger Entry.actual_qty

也就是不只看订单换算，还要看真实库存是否按库存单位准确结算。

常见误判

日志中出现 422 不一定是主链路失败。

如果测试本来就是探测不存在主数据、校验参数或触发业务规则，422 可能是预期结果。

判断时要看响应包络：

{
  "ok": false,
  "status": "error",
  "code": "VALIDATION_ERROR"
}

而不是只看 HTTP 状态码。

测试分层建议

myapp/tests/http/         HTTP 冒烟、链路、幂等、并发测试
myapp/tests/unit/         服务层与工具函数单元测试
myapp/tests/integration/  依赖真实站点上下文的服务链路回归

推荐顺序：

先跑单接口测试
再跑幂等和并发测试
最后跑链路 smoke test
需要全量回归时再跑整份文件

Frappe Docker 本地开发命令速查

Wed, 20 May 2026 00:00:00 GMT

这篇从 frappe_docker 项目文档整理，主要用于本地开发时复制命令。

开发模式启动

使用 noproxy，直接暴露端口：

docker compose \
  -f compose.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.noproxy.yaml \
  up -d

如果项目里有封装脚本：

./start-dev.sh

生产模式启动

Traefik + HTTPS：

docker compose \
  -f compose.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.traefik.yaml \
  -f overrides/compose.https.yaml \
  up -d

如果项目里有封装脚本：

./start-prod.sh

停止服务

docker compose down

或者：

./stop.sh

进入 backend 容器

docker compose exec backend bash

创建新站点

在容器内执行：

bench new-site \
  --mariadb-user-host-login-scope=% \
  --db-root-password <db-root-password> \
  --admin-password <admin-password> \
  sitename.localhost

注意把密码和站点名换成自己的值。

migrate

docker compose exec backend bench --site sitename.localhost migrate

进入 bench console

docker compose exec backend bench --site sitename.localhost console

查看日志

docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f websocket
docker compose logs -f queue-short
docker compose logs -f queue-long
docker compose logs -f scheduler

重启单个服务

docker compose restart backend
docker compose restart frontend
docker compose restart websocket

myapp 开发注意事项

apps/myapp 在开发环境中通常会 bind mount 到容器：

/home/frappe/frappe-bench/apps/myapp

开发态修改代码后通常可以直接反映到容器中；如果涉及前端资源或静态文件，可能还需要：

docker compose exec backend bench build

代码检查

进入 app 目录：

cd apps/myapp

运行 ruff：

ruff check .
ruff format .

运行 pre-commit：

pre-commit run --all-files

常用环境变量

.env 中常见配置：

ERPNEXT_VERSION=v16.x.x
DB_PASSWORD=<db-root-password>
FRAPPE_SITE_NAME_HEADER=sitename.localhost
HTTP_PUBLISH_PORT=8080
HTTPS_PUBLISH_PORT=443

FRAPPE_SITE_NAME_HEADER 很适合单站点调试，用来覆盖 Host 头解析。

常用服务说明

configurator：初始化服务，配置数据库和 Redis，执行完会退出。

backend：Python / Werkzeug 后端服务。

frontend：Nginx 反向代理和静态资源服务。

websocket：Node.js Socket.IO 实时通信服务。

queue-short：短任务队列 worker。

queue-long：长任务队列 worker。

scheduler：定时任务调度器。

注意事项

本地开发用 bind mount 很方便，但 staging / production 更建议把自定义 app 烘焙进镜像。

如果 staging 继续挂载 ./apps/myapp，而服务器上没有源码目录，可能会把镜像里已经存在的 myapp 覆盖掉，导致：

ModuleNotFoundError: No module named 'myapp'

myapp Staging 部署问题与解决速查

Wed, 20 May 2026 00:00:00 GMT

这篇从 frappe_docker/STAGING_DEPLOYMENT.zh-CN.md 整理，所有真实服务器信息都用占位符替换。

当前 staging 方案

流程：

Lint
-> Build myapp staging image
-> Push to GHCR
-> Deploy staging stack by SSH
-> 首次建站 init-site.sh
-> 后续升级自动 bench migrate

核心原则：

服务器只保留部署骨架
不再在服务器挂载 apps/myapp 源码目录
myapp 烘焙进镜像
首次部署允许“容器起来但站点未初始化”

GitHub Actions Secrets

常见 secrets：

STAGING_SSH_HOST
STAGING_SSH_PORT
STAGING_SSH_USER
STAGING_SSH_PRIVATE_KEY
GHCR_USERNAME
GHCR_TOKEN
STAGING_SITE_ADMIN_PASSWORD

注意：

STAGING_SSH_PRIVATE_KEY 必须是完整私钥
不能填 .pub
不能只填一行公钥
建议使用无 passphrase 的 CI 专用 key
GHCR_TOKEN 至少需要读取 packages 的权限

生成 CI key：

ssh-keygen -t ed25519 -N "" -C "github-actions-staging" -f ~/.ssh/github_actions_staging_ci

本地验证：

ssh -i ~/.ssh/github_actions_staging_ci -p <port> <user>@<host>

首次部署顺序

推荐顺序：

1. Lint
2. Build myapp staging image
3. Deploy staging stack
4. init-site.sh 创建站点
5. check-staging.sh 检查

原因：

bench new-site 依赖 backend / db / redis 容器
所以必须先把基础栈启动起来

首次部署后出现这些情况是正常的：

镜像正常拉取
容器栈成功启动
首页返回 404
/api/method/ping 返回 404
deploy 脚本跳过 migrate

这通常表示基础栈已启动，但站点还没创建。

首次建站

cd /srv/frappe_docker
SITE_NAME=staging.example.com \
ADMIN_PASSWORD='<admin-password>' \
./deploy/staging/init-site.sh

底层动作：

bench new-site <site>
bench --site <site> install-app erpnext
bench --site <site> install-app myapp
bench --site <site> migrate

建站完成后，后续 deploy 就可以自动 migrate。

CORS 修改与验证

如果浏览器端要直接访问 staging 后端，需要把完整 origin 加入 Frappe 的 allow_cors。

实际读取文件通常是容器内：

/home/frappe/frappe-bench/sites/common_site_config.json

修改后至少重启：

docker compose -p staging restart backend frontend websocket

验证预检请求：

curl -sS -X OPTIONS -D - -o /dev/null \
  -H "Origin: https://frontend.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type" \
  https://erpnext.example.com/api/method/login

生效时应看到：

Access-Control-Allow-Origin: https://frontend.example.com
Access-Control-Allow-Credentials: true

注意：CORS 放开只代表浏览器能发请求，不代表跨站 Cookie / Session 一定稳定。长期使用更推荐同主域名方案。

直接访问 IP 返回 404

现象：

curl -I http://127.0.0.1:28080

返回 404，但：

curl -I -H 'Host: staging.example.com' http://127.0.0.1:28080

返回 200。

原因：

Frappe / Nginx 按 Host 头路由站点
直接访问 IP 时 Host 不是站点名
所以没有命中对应 site

解决：

FRAPPE_SITE_NAME_HEADER=staging.example.com

然后重启 staging。

常见问题：SSH 失败

现象：

missing server host
unable to authenticate

常见原因：

STAGING_SSH_* secrets 不完整
私钥内容错误
端口或用户名带空格/换行
服务器 authorized_keys 没有对应公钥

解决：

workflow 增加 secrets 校验
使用 CI 专用 SSH key
本地先用同一把 key 验证能登录服务器

常见问题：git pull 被拒绝

现象：

Your local changes would be overwritten by merge

可能原因：

服务器上的脚本只有文件 mode 变化，例如 100644 -> 100755

解决：

cd /srv/frappe_docker
git checkout -- deploy/staging/*.sh
git pull --ff-only origin main

常见问题：No module named myapp

现象：

ModuleNotFoundError: No module named 'myapp'

原因：

staging 还在沿用开发态 compose
compose 挂载了宿主机 ./apps/myapp
服务器没有这份源码目录
bind mount 把镜像内置的 myapp 覆盖掉

解决：

staging 使用专用 compose
不挂载服务器上的 apps/myapp
让 myapp 来自镜像

常见问题：数据库端口冲突

现象：

Bind for 0.0.0.0:3307 failed: port is already allocated

解决：

staging 数据库不映射宿主机端口
或使用 staging 专用 compose 覆盖端口配置

常见问题：migrate 时站点不存在

现象：

Error: 404 Not Found: staging.example.com does not exist.

原因：

第一次部署只启动了基础栈
站点尚未 new-site

解决：

deploy 脚本先检查站点是否存在
不存在就跳过 migrate
先执行 init-site.sh

常见问题：formatter 导致 CI 失败

现象：

files were modified by this hook

原因：

不是业务逻辑错误
是 prettier / shfmt / shellcheck 认为格式还没对齐

建议：

改 Markdown / YAML / JSON 后关注 prettier
改 shell 脚本后关注 shfmt 和 shellcheck
CI 日志里未显示 (unchanged) 的文件，通常就是被 formatter 修改过的文件

常见问题：恢复后短暂 503

可能原因：

数据恢复后站点仍处于 maintenance mode

解决：

bench --site <site> set-maintenance-mode off

restore 脚本也应该在末尾自动关闭维护模式、执行 migrate 并清缓存。

备份与恢复

升级前备份：

SITE_NAME=all ./deploy/staging/backup-staging.sh

恢复：

SITE_NAME=staging.example.com \
RESTORE_DIR=/srv/frappe_docker/tmp/restore-localhost-YYYYMMDD \
./deploy/staging/restore-staging.sh

注意：

数据跟着 site 走，不是跟着 app 走
恢复会覆盖目标站点数据库和文件
不要恢复清理前的旧备份
恢复前确认备份时间点

WMS / ERPNext 单机 Compose 配置注意事项

Wed, 20 May 2026 00:00:00 GMT

这篇从 wms-system 当前目录结构整理，偏环境快照和注意事项。

当前服务结构

Compose 中包含：

db           MariaDB 10.11
redis-cache  Redis cache
redis-queue  Redis queue / socketio
frontend     Nginx
erp-app      frappe/erpnext:v16.0.0

端口映射

Nginx：

ports:
  - "8080:80"

ERPNext app：

ports:
  - "8000:8000"
  - "9000:9000"
  - "5678:5678"

含义：

8080：宿主机访问 Nginx
8000：Frappe web 服务
9000：Socket.IO
5678：调试端口

MariaDB 配置

当前 MariaDB 命令：

command:
  - --character-set-server=utf8mb4
  - --collation-server=utf8mb4_unicode_ci
  - --skip-character-set-client-handshake
  - --innodb-file-per-table=1

这些配置用于：

使用 utf8mb4
避免字符集握手不一致
每张 InnoDB 表独立表空间

Redis 配置

Frappe common site config 中需要类似：

{
  "redis_cache": "redis://redis-cache:6379",
  "redis_queue": "redis://redis-queue:6379"
}

Compose 环境变量也要对应：

environment:
  - REDIS_CACHE=redis-cache:6379
  - REDIS_QUEUE=redis-queue:6379
  - REDIS_SOCKETIO=redis-queue:6379

apps 和 sites 挂载

当前挂载：

volumes:
  - ./apps:/home/frappe/frappe-bench/apps
  - ./sites:/home/frappe/frappe-bench/sites

含义：

apps 保存 Frappe / ERPNext 应用代码
sites 保存站点配置、assets、日志、私有文件和备份

注意：

sites/site_config.json 里可能包含数据库账号和密码
这类文件不适合公开提交
如果这是本地实验快照，要注意不要把真实生产配置放进去

站点配置

sites/apps.txt 中记录已安装应用：

frappe
erpnext

sites/common_site_config.json 中记录通用配置：

{
  "db_host": "db",
  "redis_cache": "redis://redis-cache:6379",
  "redis_queue": "redis://redis-queue:6379"
}

单个站点的 site_config.json 会包含：

{
  "db_name": "<db-name>",
  "db_password": "<db-password>",
  "db_type": "mariadb",
  "db_user": "<db-user>",
  "developer_mode": 1
}

不要把真实值直接写进公开笔记或公开仓库。

常用检查命令

查看服务：

docker compose ps

查看日志：

docker compose logs -f frontend
docker compose logs -f erp-app
docker compose logs -f db

进入 ERPNext 容器：

docker compose exec erp-app bash

进入数据库：

docker compose exec db mariadb -uroot -p

查看 Redis：

docker compose exec redis-cache redis-cli ping
docker compose exec redis-queue redis-cli ping

Nginx 注意事项

Nginx 挂载：

- ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
- ./sites:/home/frappe/frappe-bench/sites

这说明 Nginx 会直接读取宿主机 sites 下的静态资源。

如果页面资源 404，优先检查：

docker compose logs -f frontend
ls -la sites/assets

安全注意事项

不要公开：

site_config.json 中的数据库密码
生产站点的私有文件
private/backups
真实管理员密码
真实 token / secret

如果要把环境整理成可复用模板，建议把真实配置替换成：

<db-password>
<admin-password>
<site-name>

并提供 .env.example 或 site_config.example.json。

适合后续整理的方向

这个目录更像一个本地 ERPNext / WMS 环境快照。

后续如果继续整理，优先补：

当前站点创建命令
Nginx 配置说明
初始化数据来源
WMS 相关自定义 app 是否存在
备份恢复流程
哪些文件应该 gitignore

博客视觉资源更换速查

Wed, 20 May 2026 00:00:00 GMT

这篇记录博客里和“外观换装”有关的位置，后续换图片时不用重新翻代码。

头像

配置位置：

src/config.ts

字段：

profileConfig.avatar

当前值：

avatar: "assets/images/profile-avatar.png"

图片放在：

src/assets/images/

顶部 banner

配置位置：

src/config.ts

字段：

siteConfig.banner

开启：

banner: {
  enable: true,
  src: "assets/images/demo-banner.png",
  position: "center",
}

如果不想显示顶部大图：

enable: false

顶部氛围背景图

配置位置：

src/config.ts

字段：

siteConfig.background

当前背景图：

src: "/images/meteor-shower-background.png"

图片位置：

public/images/

更换方式：

把新图片放到 public/images/
修改 src
运行构建检查

pnpm build

常用参数

顶部背景高度：

height: "clamp(24rem, 42vh, 36rem)"

透明度：

opacity: 1

图片位置：

position: "center"
position: "top"
position: "bottom"

模糊：

blur: "4px"

缩放：

scale: 1.03

遮罩：

overlay: {
  light: "transparent",
  dark: "transparent",
}