RGC Blog

这个博客的笔记结构

Wed, 20 May 2026 00:00:00 GMT

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

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

分类只回答一件事

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

笔记
项目
博客
实验
随笔

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

标签负责具体主题

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

Cloudflare
Workers
部署
排错
Frappe
Docker
速查

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

笔记类型

当前先按这些类型整理：

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

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

写作原则

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

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

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

博客开始了

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

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

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 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 也拿去尝试。

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 公钥，不是没有后缀的私钥。

设置权限

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。

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。