The projects on hand at the same moment: a Rust + SQL site reworking its statistics query, a Next.js app retiring its service worker, a Bun + Hono service fixing a tunnel origin, a Prisma + tRPC monorepo, a C# game private server filling in data fields, a C/C++ SDL3/WASM port, and two Zola/Hexo documentation sites. 64 directories and 36 git repositories under ~/Code.

This isn’t the “I have a lot of windows open” kind of parallelism. Anyone can open windows; the hard part is making progress on all of them at once without contaminating each other.

First, why it’s even worth it

With a single project, the most expensive part of AI collaboration is waiting: ten minutes for a full test run, five for a build, however long for browser regression. During that time the only things a person can do are sit there or switch to something else—and switching back means reloading context.

The first payoff of running eight projects in parallel is exactly this: the waiting gets filled by other lines. A’s build is running while B’s failure log just comes back; C waits on a human confirmation while D’s tests go red and need fixing. The machine’s throughput gets pulled up, and the human brain no longer has idle gaps.

The second payoff is reusing a solution from one line on another. Today, figuring out in av-site that “creating an index must stay inside the same transaction block as acquiring the lock” naturally led to thinking about “the deletion order when retiring a worker” in AstroDX—both are cases of “nothing can slip in between the two steps.” That kind of cross-project intuition only happens when you have several lines in hand at once.

But the payoff has preconditions, and here they are.

Rules must be layered, not copied

~/.agents/AGENTS.md is the single source of truth; ~/.codex/AGENTS.md and ~/.dsh/AGENTS.md are symlinks to it, and ~/.claude/CLAUDE.md references it via @. To change a rule you only change that one copy—three copies will inevitably drift.

The source of truth holds only what’s universal across projects: hold conversations in Chinese, Conventional Commits, the local machine isn’t the build machine, which machine to go to remotely, how to persist tasks over 30 seconds, where the proxy is.

Project-level AGENTS.md files only describe what’s unique to that project, and some really do write them narrowly:

• av-site/AGENTS.md: all five CI steps green is the prerequisite for merging; changing OpenAPI types requires bun run gen:client; how to spin up a temporary postgres for database tests with #[ignore]; curl from the build machine needs a UA or Cloudflare returns 403; add SET default_transaction_read_only = on; before production troubleshooting.
• eagler-touhou-next/AGENTS.md: this Mac is read/write and Git only; which checkout directory on the build machine; bun is pinned to 1.4.2; where the project’s own postgres:18 container lives.
• th15/AGENTS.md is only 15 lines: the ownership of two trees.

That middle category—“which machine is the build machine”—is actually written in both files. It looks redundant, but the division of labor differs: the source of truth says “there is a build machine, pick by priority,” while the project file says “this project is fixed to this one, the checkout directory is here.” The former is a rule, the latter a fact.

There’s one more hard rule: every project must be able to state clearly “where it runs”—if you can’t write it down, the project isn’t ready to be parallelized yet.

Tasks must have an identity

Something run remotely can’t just be a ssh host 'bun run build' and done with it—drop the SSH and it’s gone, and reconnecting doesn’t tell you where it got to.

The rule in the source of truth, “remote SSH task persistence and reconnection recovery,” specifies this (shared by all projects):

Each task gets an independent ID, an independent tmux session, and an independent ~/.local/state/ai-jobs/<任务ID>/ directory. Inside the directory, run.sh begins with set -uo pipefail, umask 077, exec > output.log, trap writing the exit code into a file, echo $$ > pid, date -Is > started, then explicitly exporting PATH and HTTP(S)_PROXY.

Startup, logs, exit code, process ID, and start time are all five on disk. If SSH drops, go back by the original ID and read the status—do not resubmit. If the tmux session is gone but there’s also no exit code, the status counts as unknown: keep cross-checking the process and artifacts, and don’t treat it as success or as failure.

What’s forbidden is sharing a fixed ai-task session—several lines firing send-keys into the same session amounts to throwing commands into a shell you don’t recognize.

Recent tasks’ exit codes include both 0 and 1 (adjust-download-policy-red is 1, adjust-prod-cold is 1, a batch of adjust-consent mixed 1/0). Parallelism isn’t eight lines all green—it’s eight lines’ results each landing on disk, each queryable, with the red ones not dragging the others down.

Write to one place at a time

Two lines editing the same file at once is the number-one incident source in this workflow.

The unit of dispatch isn’t the project, it’s the file. Today the write-sets of the four lines are: av-site/infra/migrations/*, AstroDX/apps/web/public + src/lib, acgn-flow/src/server/*, drama-site/apps/web/src/*. The four groups are mutually disjoint.
(This is part 1 of 2 of the same post.)

Conversely, if the same package.json or root tsconfig needs to be changed, make them sequentially dependent: finish one before starting the next. Hard parallelism here only produces git conflicts and edits that overwrite each other.

When shared configuration must be changed across projects, I’d rather pause the line I’m on and wait for it to land.

Verification is tiered by scope of change

What most easily slackens under parallelism is verification, because every line wants to wrap up quickly.

The rule is tier by change, not by how much time is free:

• One file changed → lint just that file, run just that test file; it can be done locally.
• Cross-module change → go up to the build machine and run the whole-repo check for that project (AstroDX’s scripts/remote/verify.sh runs 739 tests + lints 719 files).
• Anything with side effects (migrations, deployments, data fixes) → add real-device acceptance; for example, av-site changes to playback must run check-live-playback.py with a rate-limit round, and all-green smoke isn’t enough.

The only valid reason to downgrade verification is “this change isn’t worth that cost,” never “I’m busy right now.” Being busy is precisely what parallelism creates; trading busyness for cheap verification just pays back the time parallelism saved.

The costs, recorded in plain sight

The above is method; below is the ledger.

Context dilutes itself. With eight lines in hand, the memory of each grows thin. So the moment a line lands, “why it was changed this way” must go straight into a code comment or that project’s docs—don’t count on remembering next time. Of the 86 lines in 0055's migration file, 52 are comments, and AstroDX’s docs/verification/service-worker-retirement-2026-10-30.md even records when the script itself went wrong—both for this reason.

Review is the bottleneck, and it doesn’t scale with parallelism. Eight lines each produce output, and the merge decision all lands on one person. So better to let the AI go slower and produce less than to have it change 20 files at once—a giant change that can’t be decomposed takes longer to read through than to do yourself.

Build-machine resources are shared. A load average of two to seven looks low, but that’s headroom on 128 cores; at the same moment, two or three of several tmux sessions are running browser regressions and competing for memory. Lines running full test suites need to be scheduled on idle cores; single-core cases like taskset -c 0 get slowed by other lines, and timing issues on a slow CPU only surface under that condition—which is both a blessing and a trap.

Task directories grow if not cleaned. 372 directories, 3.1 GB, four and a half days of uptime. After a run, --keep keeps the evidence, and it should be swept a week later; it hasn’t been swept yet, which already counts as debt.

One more thing often overlooked: parallelism makes “done” cheap. One line goes red and nobody cares; another goes green and keeps moving, and the red one gets buried. So at the end of each day, look through the directories with non-zero exit codes, not at “how many were delivered today.”

Who this suits

Who it doesn’t suit: people whose changes are strongly linear, who can only think about one thing at a time, who dislike writing rule files.

There’s only one prerequisite for it to suit you: the project must already be verifiable in a remote form. A build machine, a verify script, and “where to run it” written into files—with all three in place you can split lines; missing any one, and raising parallelism only moves “stuck” from local to remote.

As for the AI’s side, it neither knows nor cares that other lines are running. It’s kept apart by the “don’t touch that directory” constraints in rule files, by the identity of task directories, by disjoint write sets. All these partitions are built in advance by a human; the AI just runs inside them.

When eight lines run at once, what I’m actually doing is quite boring: reading exit codes, watching logs, judging which line should continue and which should stop, writing the reasons into files. The real parallelism happens on disk and CPU; the human part remains serial—except what’s serialized is judgment, not typing.

(This is part 2 of 2 of the same post.)

It deleted the entire Adjust runtime. Under packages/api/src/adjust/, 7 of the 8 files were deleted outright, and diff --stat was 4 insertions and 292 deletions.

No conflicts. No compile errors. CI was green.

How the deletion slipped in

The merge’s two parents are e5051db93 and 93173a00b (main), and the merge base is e11e286ff. On the base, these 8 files were intact, and all the git ls-tree references were present.

The problem was that the zsf line had already deleted them: that line was meant to implement a different feature, and from its perspective Adjust was “something extra that existed on main,” so removing it made the local tree cleaner. When merging, git therefore faced “deleted on one side, untouched on the other”—under the three-way merge rules, the deletion counts as zsf’s change and is kept as-is.

This is not a revert, nor is it a conflict. A conflict at least stops and asks you. This kind of merge takes effect silently, and the commit message only says “Merge latest main.”

Even more conveniently, there were no compile errors after the deletion. That’s because in the same batch of commits, all references to import "@nq/api/adjust", adjust-tracking, and adjust-session were deleted along with it—otherwise, with the references still present and the implementation gone, pnpm typecheck would have gone red.

So the whole set of green lights—“tests green, typecheck green, build green”—was completely useless here. They check whether it compiles, not whether the feature is still there.

How it was found

A single command:

git grep '@nq/api/adjust' upstream/preview

Zero hits.

That was the lesson, short enough to serve as a mantra: After merging across major branches, don’t just look at typecheck—grep for the feature name. If a few more people merge after 2aa1194ed, this clue will be completely buried—the feature name is still in the docs, but the window in the minds of people who remember it is only a few days.

After it was found, 88cdad163 restored the runtime with 86 files and 6,117 insertions, filling in A2/A3/A4/A6/A7 all at once. As of 10-23, the audit document 09-adjust-audit.md still concluded “0%—there is no Adjust integration anywhere in the repository.”

Restoring it was only half the battle; the next part was where the real thinking began.

8 Event Tokens are not 8 events

The vendor provided 8 Event Tokens, operations had already created them in the dashboard, and they required first purchase and refunds to carry amounts. The easiest implementation would be “send whenever you see a Token”—8 if statements.

But events are not equal. Split by “who is the single source of truth,” they fall into two categories from the start:

So the first thing the enqueueing code does is split the sets:

/** 带收入的事件 —— 入队时必须拿到合法金额与币种，否则落 BLOCKED 而不是发一条 0 元收入。 */export const ADJUST_REVENUE_EVENTS: ReadonlySet<string> = new Set(  ADJUST_INTERNAL_EVENTS.filter(e => e.revenue).map(e => e.key),);

After the split, there are several rules hardcoded in the code and impossible to change from the dashboard.

One payment can only be recorded once. When first purchase matches, send only first_purchase and no longer send purchase:

function mappingCandidates(internalEvent: string, firstPurchase: boolean): string[] {  if (!ADJUST_REVENUE_EVENTS.has(internalEvent)) return [internalEvent];  const chain = internalEvent === "PURCHASE" || internalEvent === "FIRST_PURCHASE"    ? ["PURCHASE"]    : [internalEvent, "PURCHASE"];  return firstPurchase ? ["FIRST_PURCHASE", ...chain] : chain;}

The candidate order puts specific events before generic ones, and stops at the first match. When FIRST_PURCHASE is not configured, it naturally falls back to the type event or PURCHASE, and the whole chain doesn’t break just because one line is missing in the dashboard.

Non-revenue events have no fallback. Note that the first line above directly returns [internalEvent]. If EPISODE_UNLOCK lacks a mapping, it falls to BLOCKED / MISSING_S2S_MAPPING and does not fall back to PURCHASE—if it did, it would pointlessly record a 0-yuan revenue entry, creating a bunch of gaps in reports that are harder to trace than a missing entry.

Unlocks do not double-count revenue. Coins are bought in advance on top-up orders; unlocking merely spends them. Therefore, the revenue for first_unlock / episode_unlock is always empty.

Membership activation and revenue are two events from the same order. Both vip_activation and purchase are generated by the same order, so the unique key of the delivery row is expanded from (order_id, environment) to (order_id, environment, internal_event). currency is also made nullable at the same time—stuffing the string "INVALID" into non-revenue events would get rejected by the vendor’s currency validation.

Every missing piece must be visible. If any link in the chain is unsatisfied—no identity, environment mismatch, missing mapping, missing S2S token, invalid amount—write a BLOCKED row with a reason code; do not silently drop it. Black holes like “configured but no identity” must be visible in the dashboard’s postback records; otherwise you’ll forever be saying, “It should have been sent.”

The callback side

GET|POST /api/webhooks/adjust/callback. Map status codes to their retry rules: 200 accepted or already received, 400 this one’s dead, don’t resend, 401 auth failed, 404 not paired yet, 503 our side had a temporary failure.

Auth nonce on both sides timingSafeEqual; the idempotency key is a hash of created_at; the receipt is pinned only on the first attempt (where callbackAt: null).

Once this was running, I ran into two vendor behaviors, both of which made it into code comments and tests:

• 2xx comes in three shapes: {"status":"OK"}, an empty body {}, and an empty string. The original check only recognized the first, so the other two were treated as UNKNOWN, and UNKNOWN doesn’t retry automatically — a payment already recorded on the vendor side would never reconcile. Changed it so any 2xx counts as SENT.
• {order_id} is not a placeholder. It isn’t in the 262-entry placeholder table behind help.adjust.com, so writing it into the callback URL leaves it unreplaced and the other side receives the literal text. But the S2S callback_params appends the real value to the end of the URL, so the same key shows up twice, literal first, and first() always picks up {order_id}. The parser now walks getAll and skips {...}-shaped segments.

After the second fix I deliberately re-verified the worst case: reverted the template to the old form with {order_id}, created a transaction and ran it end to end, and the receipt got pinned as usual. Only after confirming that production was running the new parser — and not just “the template happened to be clean” — did I feel safe shipping it.

Two gates, deliberately different

AD_REAL_SENDING_ENABLED=0 guards Meta CAPI and TikTok — neither has a sandbox, so a preview sends something that’s really recorded in the ad account. Adjust is therefore unaffected: it has a real sandbox, and adjustEnvironment() maps previews to SANDBOX.

To silence Adjust previews too, use the other gate, ADJUST_S2S_ENABLED=0.

The gates are separate because the reasons differ. One is “don’t pollute the real account”; the other is “this pipeline shuts itself up.” Merge them into one, and later, when you only want to silence one side, you’ll have to rewrite it.

Wrapping up

Production is a separate a2bcb4351, based on release-v1.2.45, containing only what was verified on preview — no Mock/Kafka scaffolding and no consent modal.

In hindsight, the cost of a merge accident like 2aa1194ed isn’t in “getting it back” — from the merge (10-27 10:41 UTC+7) to the recovery commit 88cdad163 (same day, 19:47 UTC+8) was eight hours, and not a single line was lost from git. The cost is in those eight hours: the feature was assumed to “already exist,” nobody touched it, and regression tests can’t cover a module that doesn’t exist.

The cheapest line of defense is turning grep into a fixed post-merge step. Typecheck answers “does it compile”; only grep answers “is it still there.”

Let me lay out the background first, otherwise that comment just reads like generic hand-wringing.

What we’re fixing isn’t “can’t find it”

0001_init.sql hands work.code a bare TEXT UNIQUE, i.e. UNIQUE (code), case-sensitive. But every read path on the site matches on lower(code) = lower($1).

The consequence of that mismatch isn’t “can’t find it” — it’s one title splitting into two rows in the database. In the 2026-08 batch the catalog pusher started sending the code as DASS-966 instead of dass-966; upsert_work's ON CONFLICT (code) didn’t match, so a new row got inserted. In production, three pairs actually split: DASS-966, DSOD-009, START-597 — merged by hand on 2026-08-29.

The symptoms after a split aren’t errors either; they’re two classes of silent failure:

1. Half the data. The old row holds source_link, work_embedding, frame_embedding; the new row has only metadata. And ... WHERE lower(w.code)=lower($1) LIMIT 1 has no ORDER BY, so which row you get is up to the query plan. At the time, DSOD-009 and START-597 were getting the row with no play sources — the watch page returned 200 with not a single source.
2. A flat 500. Any scalar subquery of the shape = (SELECT ... WHERE lower(code)=lower($1)) raises more than one row returned by a subquery used as an expression when it hits multiple rows. Unfavorite, remove-from-playlist, and the similar-titles fallback all have that shape.

At the time, 0046_anime_import.sql:117-131 deliberately didn’t create the unique index right away, on the grounds that the existing dirty data would blow up the entire --single-transaction migration. Now that the data is merged clean, 0055 is here to tighten things up.

Why keep that case-sensitive constraint

What we’re creating is CREATE UNIQUE INDEX work_code_lower_key ON work (lower(code)). So can the old work_code_key (UNIQUE (code)) just be dropped along the way?

No. external_source_map.code is a foreign key pointing at work(code), and a foreign key requires a unique constraint on the referenced column, so DROP work_code_key would fail on dependency. And UNIQUE (lower(code)) is strictly stronger than it, so keeping it has no downside.

The non-unique functional index idx_work_lower_code created by 0046 can go, though — same columns, fully covered by the new unique index; keeping it just adds write amplification.

First judgment call: why it’s all wrapped in one DO block

Because LOCK TABLE only works inside a transaction block.

The production migration goes through psql --single-transaction in migrate.sh, which has a transaction block — no problem. But the local procedure recorded in tools/ugc-smoke/README.md is per-file psql -f, autocommit, no transaction block — a bare LOCK there just errors with LOCK TABLE can only be used in transaction blocks, and the local smoke DB ends up missing this unique constraint, which is the one and only thing this migration does.

A DO block carries its own implicit transaction, so it holds under both procedures. That also explains why LOCK and CREATE INDEX can’t be split into two statements.

Why grab the strongest lock right at the start

CREATE UNIQUE INDEX takes a SHARE lock, which blocks writes; DROP INDEX needs ACCESS EXCLUSIVE. Create-then-drop means a second lock upgrade inside the same transaction.

An online write that squeezes in between (the UPDATE work in increment_view) can’t get RowExclusive and queues; we then wait for it to yield; a cycle forms; deadlock detected; the whole migration rolls back. This was reproduced on the production database.

There’s an easy assumption to make: “nobody’s writing while the migration runs anyway.” It doesn’t hold: compose runs migrate to completion before it touches the api container, so during the migration the old api is still serving and increment_view keeps writing.

So one LOCK TABLE work IN ACCESS EXCLUSIVE MODE at the top grabs the strongest lock and never upgrades again — a cycle has no way to form.

Second judgment call: this is where I got it wrong

The first time this went to prd, lock_timeout was followed by “fail fast if the lock can’t be had.” The reasoning at the time: migrate exits non-zero, the api isn’t rebuilt, the old api keeps serving — so failing is the safe direction.

That judgment was wrong.

docker compose up -d does not preserve the old container just because migrate exited non-zero. It rebuilds api/web as usual; the new container just gets stuck at Created and won’t come up — depends_on: migrate: service_completed_successfully isn’t satisfied.

Net result: the migration didn’t take effect and the site went down outright. And the prd work table always has increment_view writing to it, so there was never any guarantee of grabbing ACCESS EXCLUSIVE within 15 seconds. An ordinary deploy took the site out.

The right approach is short timeout + repeated retries: wait only 2 seconds each round, let the queued write transactions finish, then try again. Online writes are all short transactions, so within a few rounds a window is bound to open. Only if 60 seconds pass without getting the lock do we RAISE — that means a long transaction is sitting on work, which calls for human intervention rather than forcing it.

FOR i IN 1..30 LOOP    BEGIN        PERFORM set_config('lock_timeout', '2s', true);        LOCK TABLE work IN ACCESS EXCLUSIVE MODE;        EXIT;    EXCEPTION WHEN lock_not_available THEN        IF i = 30 THEN            RAISE EXCEPTION '60 秒内拿不到 work 的 ACCESS EXCLUSIVE 锁（有长事务压着？先查 pg_stat_activity 再重试）';        END IF;        PERFORM pg_sleep(1);    END;END LOOP;PERFORM set_config('lock_timeout', '0', true);

A separate BEGIN/EXCEPTION per round creates an implicit savepoint, so a failed lock attempt rolls back only that round and doesn’t poison the whole migration transaction.

Error messages need to speak human

There’s one more gate before you create the unique index. If duplicates exist, it hands back a sentence you can act on directly, rather than a duplicate key value:

SELECT count(*), string_agg(lc, ', ' ORDER BY lc)  INTO dup, sample  FROM (SELECT lower(code) AS lc FROM work GROUP BY 1 HAVING count(*) > 1 LIMIT 20) t;IF dup > 0 THEN    RAISE EXCEPTION      'work 存在 % 组大小写重复 code，须先人工合并（保留握有 source_link/向量的那行）再跑本迁移：%',      dup, sample;END IF;

“Keep the row that holds the source_link” has to be written in — reverse the merge direction and data is still lost, the unique index still gets built, and from then on that movie simply has no playback source.

Wrapping Up

EXECUTE 'DROP INDEX IF EXISTS idx_work_lower_code';EXECUTE 'CREATE UNIQUE INDEX IF NOT EXISTS work_code_lower_key ON work (lower(code))';

Both go through EXECUTE: inside a DO block you could write the DDL directly, but the whole script uniformly uses EXECUTE to concatenate strings, tied together with the variables above so it reads as one thing from start to finish.

At the end of the migration file there’s also a ANALYZE work;, so the planner sees the new index as quickly as possible.

Looking back now, the file is 86 lines in total, and comments account for 52 of them. The longest passage is the record of that outage, reading “⚠️ This one was bought with production downtime”… Without it written down, the next person (or me three months later) will see “2 seconds × 30” and just think it’s verbose, then optimize it back to “fail fast.”

Three related things happened the same day: the comment system moved from Twikoo+Waline to Artalk, the license changed from CC BY-NC-SA 4.0 to CC BY 4.0, and AI crawlers were let through with llms.txt generated. This post is about the cost of config layering, plus the GEO and attribution side of things.

De-sensitizing isn’t deleting the values

_config.yml is public, so writing a key into it is the same as publishing it. But a Hexo build still needs the real values, so the approach is layering:

# _config.local.example.yml（进仓库）hexo_submit_urls_to_search_engine:  baidu_token: ""  bing_token: ""llm_tagging:  api_key: ""encrypt:  categories:    - { name: 加密, password: "" }

Copy it to _config.local.yml and fill in the real values; the build deep-merges them with --config _config.yml,_config.local.yml. All four scripts — build / server / dev / push — have the merge arguments built in.

The upside is obvious: no real values in the repo, and the template tells the next person what to fill in. The downside is just as obvious: every command has to remember to carry that second config file, and forgetting it doesn’t throw an error — it degrades silently.

The two directions of forgetting

The first direction is a build that fails outright. After api_key was moved out of llm_tagging, _config.yml is left with only an empty parent key, and running hexo clean without --config throws an error on the empty config. So the hexo clean in clean and dev got the merge arguments too — even a command like “clean”, which looks unrelated to config, has to carry them.

The second direction is subtler: leave out the passphrase for encrypt.categories and the build won’t fail — posts in encrypted categories are simply output in plaintext. So there’s a warning line next to the encrypt block in _config.yml:

# ⚠ 不带 _config.local.yml 合并构建时，加密分类的文章会以明文输出

A config whose failure mode is “leak” is far more dangerous than one whose failure mode is “error”. The former needs someone to actively go look; the latter at least goes red.

The GEO part

Also that day: robots.txt now explicitly allows the major AI crawlers — GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot and friends — and points at llms.txt and the two sitemaps; a new scripts/llms-txt.js was added, generating /llms.txt at build time.

The generator groups by first category, one - [标题](绝对URL): 摘要 line per post, and the summary strips code blocks, HTML and Markdown marks, truncated to 100 characters. Two edge cases are worth mentioning:

• Encrypted posts are kept out of llms.txt so the summary can’t leak. After hexo-blog-encrypt processing, password is deleted from the post object, so the check has to re-read the frontmatter from the source file — the in-memory object can’t be trusted;
• An individual post can opt out with llms: false in its front-matter.

On the sitemap side I tried hexo-generator-seo-friendly-sitemap's index-style splitting and rolled back to the official hexo-generator-sitemap two and a half minutes later: the site has only about 80 posts, so splitting into post/page/category/tag tables buys too little, and the official plugin is more actively maintained anyway. The llms.txt and robots changes stayed.

Attribution and license

Also that day, seven AI-drafted posts uniformly got copyright_author: Claude Opus 4.8 and copyright_author_href added, so the “article author” in the copyright box shows the collaborator instead of just me.

The license moved from CC BY-NC-SA 4.0 to CC BY 4.0: attribution, commercial use and derivatives allowed. I thought one thing through while making the change — a fair amount of what’s on the blog was already assembled from client-side corpora, official docs and material from all over, and the friction of the non-commercial restriction outweighed the benefit.

Wrapping up

After config layering, the public repo really is clean, but the system’s default state changed too: previously "just run hexo g" would build a correct site; now you have to remember the merge. Wiring it into every entry point only makes it the default, not automatic — anyone cloning the repo still has to cp the template and fill in values.

If someone asks again someday why the keys can’t just go back into _config.yml, the answer isn’t the word “insecure” — it’s: the public config and the buildable config are two different things from now on.

/music/ holds 188 <meting-js>, and inject also contains one fixed player. The tags themselves are still there, but the script injection is gone, so the page just shows a row of empty custom elements.

At this point the story should be “the upgrade broke the players, so roll back or hand-write the inject.” But I measured the baseline first, and the result was a little surprising.

Before the upgrade, it was already zero

meting-js defaults to MetingJS’s built-in backend api.i-meto.com. That service is already dead: its responses carry no CORS headers, so every browser request fails. In other words, not a single player on the live site had been rendering for a while — nobody had just bothered to count.

The theme upgrade isn’t the culprit; it merely pried up a floorboard that had rotted long ago. That distinction matters: roll back the version and the page returns to a state where “the player code looks like it’s there, but the count is still zero,” and you keep assuming it’s fine.

Hand-writing the inject: order is a hard constraint

The fix is to include them yourself, in order, inside inject:

<link rel="stylesheet" href="https://registry.npmmirror.com/aplayer/latest/files/dist/APlayer.min.css" media="print" onload="this.media='all'">...<script src="https://registry.npmmirror.com/aplayer/latest/files/dist/APlayer.min.js"></script><script>window.meting_api="https://meting-api.saop.cc/api?server=:server&type=:type&id=:id&r=:r"</script><script src="https://registry.npmmirror.com/meting/latest/files/dist/Meting.min.js"></script>

window.meting_api must be set before Meting.min.js; one line later and it has no effect. For CSS, use media="print" + onload to switch to all, which doesn’t block first paint.

The pjax glue script was actually dead code

The theme also used to have a pjax hook that destroyed and rebuilt destroyAplayer on page switches. Looking into APlayer 1.10.1, window.aplayers is no longer maintained, so that destroyAplayer had nothing to destroy in the first place.

MetingJS v2, meanwhile, is a standard custom element, so on page switches it rebuilds and destroys itself via connectedCallback / disconnectedCallback. So the conclusion this time is no glue: let the element own its own lifecycle.

After fixing it, count

Measured after the change:

• players rendered: 0 → 167/188;
• after a pjax round trip, every in-page player is rebuilt;
• the fixed player stays the same DOM node throughout, with playback uninterrupted.

Of the remaining 21, twenty are type="album" — the self-hosted Meting API doesn’t support that type yet and returns 400. The other one or two are intermittent failures caused by rate limiting under 188 concurrent requests. Both are on the API server side and unrelated to this repo; the commit message says as much, and I didn’t count them as “fixed.”

167/188 isn’t a perfect score, but it’s a number you can re-check: render count, pjax round trip, and fixed-node identity each have their own observation point.

When upgrading, separate the two accounts first

The most expensive part of a dependency upgrade isn’t editing config; it’s being able to say clearly, before the upgrade, what things actually look like right now. This time the baseline was a single sentence — zero — and it decided every judgment that followed:

• if the zero had been caused by the upgrade, I should suspect the 5.7.0 changes, or even roll back;
• if the zero was an old debt and the upgrade merely made it visible, I should fix the backend and the injection order, not roll back.

Along the way I also cleared out a piece of dead code. Had I been lazy and copied destroyAplayer verbatim into the new inject, it would have “worked” too — it would just do something useless against an empty array on every page switch, and the next person would have even less chance of seeing why it exists.

Measure what things looked like before, then decide what the upgrade broke.

The migration ultimately succeeded. But those earlier commits were almost all patching the same category of thing: assumptions the platform used to make on my behalf. This post records them in order of discovery, not in commit order.

One hop lands on 0.0.0.0:3000

Before switching production, I tested in preview: the 302 landing point for /r/<渠道码> was https://0.0.0.0:3000/, and the same applied to the callback redirects after successful and failed Google login. If the redirect entry point had only been discovered on production switch day, every short link on the site would have broken at once.

The root cause is in attachRequestMeta of next-server.js: in standalone mode, next-server holds the hostname/port it listens on and prioritizes them when constructing the request URL, so the experimental.trustHostHeader branch is never reached. On Vercel, the platform automatically trusts Host (config.js is enabled at hasNextSupport), so this was never exposed before the migration. In testing, neither Host nor X-Forwarded-Host affected req.url; only the protocol followed X-Forwarded-Proto.

The fix is a newly added lib/public-origin.ts: take the Host header (the origin is reachable only through the tunnel, and Cloudflare writes Host based on the domain the visitor requested), and for the protocol accept only https from X-Forwarded-Proto. Deliberately do not trust X-Forwarded-Host—visitors can supply it themselves, Cloudflare passes it through unchanged, and trusting it is an open redirect.

I also replaced openapi.json and llms.txt along the way: they used to prioritize reading XFH to build the site root, which is forgeable after self-hosting, and the endpoint is cached at the edge for an hour, which amounts to cache poisoning.

Same commit, prod and preview fight over one image tag

Both sides build nav-site:<sha>. But the same commit does not produce identical artifacts on both sides: the database connected at build time, prerendered data, and NEXT_PUBLIC_* can all differ. Whichever builds later takes over the tag—in testing, when production built later, the preview container’s image became an unnamed sha256:…; conversely, a production restart or rollback would end up on a build containing preview data.

Changed to nav-site:<env>-<sha>, so build, release, rollback, and cleanup all carry an environment prefix. Image identity cannot rely on commit alone; things with different artifacts should not share one name.

Secrets don’t enter the cache key

When releasing via CI on the VPS for the first time, between two commits only the deploy/ script changed (it does not enter the build context), and the whole pipeline hit cache and completed in 5 seconds. The cache itself was not the problem, but it exposed a quieter hazard: build-time environment variables are injected via BuildKit secrets, and the secret contents do not participate in the cache key. When only env changes and the code does not, pnpm build hits the old cache and the new NEXT_PUBLIC_* silently fails to take effect.

The fix is that deploy.sh passes the first 16 characters of the build env file’s sha256 as a build arg, and echo it in Dockerfile. As soon as env changes, the cache is invalidated.

EXIT trap references a local variable; a successful release exits 1

The EXIT trap in cmd_build_deploy / cmd_migrate used a function-local variable. The trap only fires when the script exits after the function returns normally; under set -u it reports “unbound”, turning a successful release into exit code 1—CI then marks every success red. After cleanup completes, trap - EXIT is removed.

pg-verify treats “empty vs. empty” as a match

When running the import against Neon for the first time, the source database failed to connect because of a certificate parameter. Yet pg-verify output “✓ sequence values match”—both sides were empty results, and since the table loop was empty there was no ✗ either. Although the script ultimately exited non-zero because of set -e, it reached no clear conclusion; on the night of the switch, it could easily have been read as a pass.

Now it first confirms both ends are reachable and that the source database really has tables under public; otherwise it exits 2 immediately. One more note: for libpq with sslmode=verify-full, sslrootcert=system must be added; Node’s pg driver does not recognize this parameter, so the connection string used by the app should contain only sslmode=verify-full.

Backups in a public bucket

The original recommendation was to create a new private backup bucket; later we decided to use the primary bucket nav-bucket directly—it has a public CDN domain attached, is publicly readable, and its object keys contain timestamps that make them guessable. The database contains user emails, password hashes, and partner keys; uploading it in plaintext would be equivalent to making it public.

So everything is age-encrypted before upload; if BACKUP_AGE_RECIPIENT is empty, the upload is refused outright (fail-closed), and ciphertext is placed under a prefix with a random suffix. The decryption private key is in /opt/nav-site/env/backup-age.key; a separate copy must be stored outside the machine: if the machine is lost entirely, the backups on R2 can only be decrypted with it.

Splitting one key into three

CHANNEL_REPORT_SECRET, USER_SESSION_SECRET, ADMIN_SESSION_SECRET, and CRON_SECRET all used to fall back to the same value, so the validity of externally shared links ended up tied to a key whose name gave no hint of the connection. When we split them apart during the migration, deploy.sh refuses to publish if any one of them is missing.

Among them, changing CHANNEL_REPORT_SECRET invalidates every externally shared link and QR code already sent to partners, so it must be stored somewhere other than the server; the others can be rotated at any time, and the only cost is that whoever happens to be logging in fails once. Keys that can be rotated at any time and keys that can’t must not look the same.

A few more that look harmless but bite

• fail2ban on this machine bans you for 24 hours after 3 authentication failures. When you can’t connect, find out why first — don’t go guessing usernames.
• sshd has port forwarding disabled, so migrations, script runs, and database queries all happen on the server itself; there is no SSH tunnel to fall back on.
• The migrator keeps no record table. It reruns everything by filename every time, so migration files must be idempotent.
• A deploy normally takes about 7 seconds with zero failed requests, and a bad version that won’t start is rolled back automatically. But Docker’s service-name resolution ignores health status: a version that can listen on the port yet returns wrong responses will receive roughly half the traffic during the health-check window, which lasts up to 30 seconds. That boundary is written into the runbook; we didn’t pretend it doesn’t exist.
• Run a restore drill at least once a quarter — a backup that has never been restored isn’t a backup.

The defaults after the move

Vercel trusted the Host for you, gave every build its own identity, guaranteed that your backup bucket was private, and said “consistent” for you when a result was empty. Self-hosting doesn’t make these things disappear; it turns them from the platform’s defaults into your own defaults: one publicOrigin, one <env>-<sha> label, one sha256 build arg, two preflight checks, and one age public key.

What really matters in a migration checklist is never the commands — it’s whether each of these assumptions has been caught, one by one.

Official docs referenced in this post: Next.js 自托管, Serwist, PM2 配置项, postgres 镜像说明

I’ve been self-hosting three or four Next.js projects back to back lately, so here’s a record of a few pitfalls I hit. Claude writes features amazingly fast — pages, tRPC routes, Prisma schemas all churned out in one go and they just run. But the moment deployment and wrap-up come around, it’s back and forth, the same file edited over and over. Everything below is the “build passes but it won’t run” category, with zero warning signs locally…

Enough chatter — let’s get to it!

The standalone multi-stage image: only one of these was a real pitfall

I originally wanted to title this “four pitfalls,” but the git log slapped me in the face~ Over its entire lifetime, the Dockerfile in vns-next has only been touched by 4 commits: 404a769 created it, then 0b7117c, 037ccf4, and fefd366 each changed it once. And three of the items below were already written correctly in the very first commit — I never actually “hit” them.

First, the one I actually hit. The build base in 404a769 was originally a plain oven/bun image, and it died outright, so 0b7117c added node:

# 注意：不能用纯 oven/bun 镜像——prisma/next 的 CLI shebang 是 #!/usr/bin/env node，# 构建环境需要 node；bun 只作为包管理器/脚本运行时拷入ARG REGISTRY_MIRROR=docker.ioFROM ${REGISTRY_MIRROR}/oven/bun:1 AS bun-distFROM ${REGISTRY_MIRROR}/library/node:24-bookworm-slim AS builderCOPY --from=bun-dist /usr/local/bin/bun /usr/local/bin/bun

The oven/bun:1 image has no node at all, so prisma generate dies the moment it runs — but the error only says the CLI can’t find an interpreter, and without looking at the shebang you’d never guess why. The fix: use node:24-bookworm-slim as the base and just COPY a single binary out of the bun image as the package manager.

The other three were already in place in the first commit. Here are a few key excerpts (the original file has no numbering; I’ve split them up for posting):

# Dockerfile:23-24 —— prisma.config.ts 里那句 if (!url) throw 是无条件抛错的，# 而 generate 根本不连库，所以构建期得塞个占位值ENV SKIP_ENV_VALIDATION=1ENV DATABASE_URL="postgresql://build:build@localhost:5432/build"

# Dockerfile:26-28 —— NEXT_PUBLIC_* 在构建期内联进客户端 bundle，# 改站点域名必须重新 build，所以要走 ARG 而不是运行时环境变量ARG NEXT_PUBLIC_APP_URL=https://example.comENV NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL}

# Dockerfile:49 —— standalone 的文件追踪可能漏拷 Prisma 生成的客户端资产（含 wasm/schema）COPY --from=builder --chown=nextjs:nodejs /app/src/generated ./src/generated

I think the NEXT_PUBLIC_* one is the easiest to overlook: it’s not a runtime variable, it gets inlined as a literal into the client bundle at the moment of next build. I deliberately wrote it out again in deploy/README.md:153-154 — change a variable like this and you must --build and rebuild the image; editing .env and restarting the container does nothing.

The second real pitfall came at b07e20d: there’s no database container inside the builder layer, and Next by default statically prerenders DB-querying pages during next build, so it’s guaranteed to throw. That one belongs to the rendering mode rather than the image itself, and I covered both the fix and how to verify it in another post; here I’ll just note what it means for the Dockerfile — it’s the only pitfall where “not a single word of the Dockerfile is wrong but the build still won’t pass,” and you can stare at the multi-stage build all day without finding a problem.

On the compose side: two round trips on registries, ports narrowing all the way down

The registry thing is pretty funny. 037ccf4 swapped all the base images to a domestic mirror + npmmirror, and 12 minutes later fefd366 rolled it back, with the reason in the message: the daemon proxy on the production machine had been fixed, and that mirror didn’t have a oven/bun image anyway. What a mess — after all that circling, only the npmmirror half survived, i.e. the ENV NPM_CONFIG_REGISTRY line in Dockerfile:16. Before you swap out infrastructure, check that the other side actually has the image you want…

The compose side converged pretty aggressively. The db service maps no ports at all; data imports and maintenance all go through docker compose exec -T db psql/pg_restore's stdin pipe:

db:  volumes:    # postgres:18 官方镜像的卷挂载点改为 /var/lib/postgresql（内含 18/docker 数据目录）    - pgdata:/var/lib/postgresql  # 不映射任何端口：整机只暴露 app 的 1270 给 Cloudflare Tunnel

The only outward-facing opening is the app service, and it’s pinned to the loopback:

app:  ports:    # 只绑本机回环，公网入口走 Cloudflare Tunnel    - "127.0.0.1:1270:3000"

The volume mount point for postgres:18 changed recently; if you copy it from an older version, your /var/lib/postgresql/data will break. And while I’m complaining: after 0b7117c removed the db port mapping, lines 43, 118, 122, and 126 of deploy/README.md still have the old port numbers — the config and docs no longer match, and AI won’t proactively sync that kind of inconsistency for you…

The two that don’t use Docker

Not every project is worth bringing compose to. acgn-flow uses PM2, with a single ecosystem.config.cjs config:

instances: 1,exec_mode: "fork",          // 单实例 fork，不用 clustermax_memory_restart: "2G",exp_backoff_restart_delay: 500,max_restarts: 15,min_uptime: "30s",kill_timeout: 5000,

The deploy script is a single line: pnpm build && pm2 reload ecosystem.config.cjs --update-env. Why fork instead of cluster isn’t actually explained in the repo; here’s what I was thinking at the time: Next already does single-process multiplexing, so wrapping another layer of cluster brings little benefit and doubles memory first — but that’s just my judgment, I never actually benchmarked it.

thdl goes the systemd route and has no deploy script — thdl/README.md:64-66 is just three hand-typed rsync commands (.next/standalone/, .next/static, public), retyped every time. A few hardening directives were added to the unit:

NoNewPrivileges=trueProtectSystem=strictProtectHome=truePrivateTmp=trueReadWritePaths=/var/www/thdl /var/log/thdl

Of the three, the Dockerfile is the most error-prone: models often mix up what exists in which layer of a multi-stage build — the bun image having no node above is a textbook case. The PM2 one was right on the first try; after all, it has few fields and plain semantics, so it’s hard to get wrong even if you tried.

Service Workers are the most crash-prone part of self-hosting

I’m giving this its own section because the problems never show up locally.
(This is part 1 of 2 of the same post.)

One thing to add about the first row: the commit message for dd40bcf5 only says “removing ‘@serwist/next’ integration”, with no reason given, and neither the README nor the config leaves any explanation. The project is indeed output: 'export' (next.config.ts:4), so I’d guess the two are incompatible, but that’s my inference, not something you can verify in the repo — compare that to the acgn-flow row, where 21e3e75's “fix Turbopack compatibility issue” is written in black and white. The bbps row has nothing.

After the bbps rework, the build became a three-stage chain: next build && node scripts/build-sw.mjs && node scripts/generate-feed.mjs. The middle script first uses esbuild to bundle src/app/sw.ts into a single bundle, then uses injectManifest to scan out/ and inject the precache manifest, and finally unlinkSync deletes the intermediate artifacts. The order can’t be reversed, because out/ is exactly what it globs.

The acg-site one is the most typical; the comment sits right there in src/components/providers.tsx:62-65: that WebView’s caching policy doesn’t match the browser’s, so it easily caches stale pages and causes a blank screen; and you have to unregister proactively, otherwise a user who opened the web version first already has the old SW installed, and going into the WebView still hits the same problem. In the same file, :36-55 also wires up isChunkLoadError() + safeReload(), with a 10-second throttle and sessionStorage deduplication, specifically to rescue the case where old pages can’t load new chunks after a release.

SW bugs never show up locally; they only show up in production, where returning visitors exist…

The grunt work of moving static assets and the feed around

bbps's RSS isn’t generated by the framework; a standalone Node script writes feed.xml into out/ after the build finishes. The side effect is that the .mjs script can’t import TS modules, so frontmatter parsing is implemented twice, once in scripts/generate-feed.mjs and once in src/lib/blog.tsx:112-123, with nearly line-for-line identical logic — knowing it’s duplicated doesn’t buy you much unless you add another layer of build on top.

Another team project has similar grunt work: after a standalone build you still have to manually copy public and .next/static into the standalone directory, and that logic is written twice — in postbuild and in the deploy script. If the two ever fall out of sync, the symptom is that all styling disappears in production while the build stays green the whole way.

There’s a more insidious one too: files uploaded at runtime by that project were initially written under public, and every standalone rebuild wipes it out, so anything users uploaded was gone after a single release. In the end we moved it to a separate directory and added a read route with path-traversal protection. The same fix also turned up that the URL check in the validation rules rejected site-relative paths — the upload succeeded but couldn’t be saved to the database. Two bugs stacked together took ages to track down.

While writing this I went back and re-checked all the line numbers and commits mentioned above, and it turned out three of the “four pitfalls” I’d originally written down were me wrongly blaming the AI, so I had to delete that section and rewrite it.

Anyway, I’m outta here~

First, a twist: the so-called “multiple parties”

Going through another one of my repos, I ran into something amusing. git shortlog -sn turned up two lines with two names, looking like two people pushing; a check of the email addresses showed they were the same person — the extra one was just my account name from clicking merge in the web UI. And of the 78 commits, 63 carry Co-Authored-By: Claude — the real “multiple parties” was never multiple people at all, it was one person plus several AI sessions. The traces of parallelism weren’t in .claude/worktrees/ either (that directory is empty, and git worktree list has only the single line for the main repo), but in the branch names: five branches with the claude/ prefix, and once two were open at the same time and eventually merged into each other.

So these boundaries below — I originally thought I was drawing them for people, but looking back, they’re mostly for “me and the several sessions I spun up myself.” Sessions share no memory whatsoever, which is worse than dealing with a colleague.

Rule files split

One team repo had fairly complete conventions — a prohibition list, version differences, commit rules — but all of it lived under one AI tool’s rules directory, and all of it was set to always apply. The problem: the other tool doesn’t read that directory at all; on its side there’s just one line of import plus the generic prompt injected by the scaffold. The two AIs have completely different context — one knows “there are other production projects on this machine,” the other knows nothing…

My own repo has a ready-made cautionary example too: acg-site maintains three sets of convention files at once, and I only updated one. The version numbers and command descriptions in the other two sat frozen at their old values — I tallied up the gory details in the post about convention files, so I won’t repeat it here.

The conclusion is blunt: keep exactly one source of truth, and point everything else at it with import. The CLAUDE.md in vns-next and thdl are each a single line; the content all lives in AGENTS.md. Change one place and both sides take effect at once — no room for drift.

But that trick only solves “one person maintaining two copies.” The multi-AI scenario adds another layer: the other tool simply doesn’t read the file you’re pointing at. So what really needs confirming isn’t “are the rules complete,” but “what actually got loaded into each agent at startup” — and there’s no shortcut; you have to try it tool by tool.

Boundary one: don’t touch anything else on the machine

The team’s machine that runs the agents has several projects running at once, so we wrote a dedicated “production environment safety constraints” rule and set it to always apply. The prohibitions go roughly like this:

• Don’t kill processes by port number
• No batch process-killing commands like killall / pkill
• Don’t modify anything under system-level config directories
• Don’t sudo any command
• Port conflicts get reported to a human only, never handled by the agent itself
• Database operations are limited to this project’s own database
• Check the blast radius before acting; if in doubt, ask first

I now copy these onto every machine that has an agent installed… When an agent sees a port is taken, its first instinct is to kill the process holding it, with no idea it’s the neighboring project’s production service.

Boundary two: don’t write APIs from memory

This pitfall is far too common — the API in the training data and the version in your package.json are not remotely the same thing… I’ve given examples of how to turn version differences into ❌→✅ comparison tables in two other posts, so here I’ll only cover the half that matters more for collaboration.

In that rules file the comparison table actually comes last; what opens it is a three-step SOP: first resolve-library-id, then query-docs, write code based on what the docs say, and spell out which scenarios “require checking the docs.” Process first, error examples second — that order matters: error examples are finite and expire, while process can cover the libraries you didn’t anticipate. You can’t list every library’s pitfalls for everyone.

There’s also a lazier route: the newer scaffolds inject a block into the repo themselves — "don’t trust your training data, go read the docs in node_modules" — complete with BEGIN/END markers, plainly meant for tools to overwrite. Nobody has to write the convention, maintenance cost drops to zero; take the freebies where you can~

Conversely, prohibitions need reasons. In the docs/ARCHITECTURE.md:115 of that repo I mentioned earlier, tucked into the tech stack table, there’s a line: client types are generated from the backend OpenAPI, do not introduce tRPC/Prisma, and the reason follows right after — the backend is a REST service in Rust axum, so a JS backend contract simply doesn’t exist. Those two are the default answers in the TS ecosystem, and an AI will install them without thinking; writing only “tRPC is forbidden” won’t stop it, because the next session can always decide the rule is outdated. With the reason attached, it’s not a commandment but a factual judgment. The same document’s :148 even limits the mirror’s permissions: the other side mirrors the DTOs with pydantic “for submission only, do not persist the structure” — a copy is allowed, but the copy must never become the source of truth.

Boundary three: large AI changes must be humanly reviewable

(This is part 1 of 3 of the same post.)

In another team’s repo, the PR template has a line of comment at the top that goes something like this: in scenarios where multiple humans work alongside AI, the PR is the only human gate before bad code reaches production, so please fill out the checklist honestly. Two items in the self-test checklist are aimed squarely at AI: one requires controlling PR size and splitting up large changes, the reason being that a human has to be able to read it in a few minutes; the other requires the submitter to have gone through the AI-written parts line by line and to own them.

Those two items are more useful than any lint rule. Lint only catches things at the syntax level; it can’t catch logic that runs fine but is wrong…

Gates in pre-commit or in CI

That same repo’s choice is to run the full type check + full unit tests in pre-commit. The reasoning is written in a comment in the config: CI only triggers when merging to main, while the staging branch is push-only with no PRs, so if you relied on CI alone the breakage wouldn’t surface until merge…

One detail worth copying—the type check is whole-project, and you can’t just feed it a single file, so the hook returns a fixed command and simply ignores the matched filenames. There’s also a secret-scanning layer on top: local scans the staged changes, CI scans the whole repo.

Comparing against a few of my own repos, the gate strength varies wildly:

The bbps case illustrates it best: lint was already there in 2025-11, --max-warnings 0 wasn’t added until 2026-02, and typecheck and check didn’t make it into package.json until 1d953fe9 a month later… The very day they were added, a type problem got caught—the third-party CSS import in comments-section.tsx that has no type declaration needed an inline comment exemption on the spot.

That repo also has a gate I hadn’t thought of, one that guards cross-language contracts specifically: CI re-runs code generation and then diffs the result against what’s committed.

- run: pnpm gen:client- name: Fail if OpenAPI/TS client drifted from committed source  run: git diff --exit-code apps/api/openapi.json packages/api-client/src/schema.d.ts

One byte off and it’s red. docs/ARCHITECTURE.md:176 writing “change the backend = change one place, clients update automatically” is a principle; these two lines are what make it impossible to violate. Same playbook as bbps: the commit that introduced this gate also says “restore a few endpoints that had drifted earlier”—and it caught pre-existing drift the moment it shipped.

By the way, here’s how Biome and ESLint split duties without stepping on each other: biome.json:20-25 in acg-site turns off the linter and assist entirely, so Biome handles formatting only and all linting goes to ESLint; CLAUDE.md:109 spells this out too, so that next time the AI doesn’t see Biome and go turn the linter back on~

28 minutes after the blow-up, the lessons became a script

This is the most beautiful passage I saw in that repo. That afternoon the backend crashed first: a comment structure referencing itself (replies: Vec<CommentOut>), perfectly legal in Rust’s type system, with cargo build, clippy -D warnings, and cargo test all green, but at startup generating the OpenAPI spec recursed infinitely, overflowed the stack, and entered a crash loop, going from 502 all the way to the whole site returning 500—a purely documentation-layer thing took down production. Nine minutes later, the second one: a newly added top-level page wasn’t in the middleware whitelist and got treated as a localized route by i18n, causing a runtime 404, while next build showed the route existed and CI was all green.

Nineteen minutes after that, a third commit turned these two lessons into two smoke tests in the deploy script, 13 lines of shell:

# ①：真跑一次二进制，拦「build 全绿但启动就崩」SQLX_OFFLINE=true timeout 30 target/release/api --openapi >/dev/null 2>&1 \  || { echo "✗ 冒烟失败——中止部署，未传镜像"; exit 1; }# ②：顶层页必须在 middleware 白名单里，否则运行时 404for _d in apps/web/src/app/*/; do  _n=$(basename "$_d"); case "$_n" in "[locale]"|dash) continue ;; esac  [ -f "${_d}page.tsx" ] || continue  grep -q "\"/$_n\"" apps/web/src/middleware.ts || { echo "✗ /$_n 未放行"; exit 1; }done

Crude as dirt—one runs the binary, the other greps—but it’s second-scale, deterministic, needs no service started or database connection, and the interception point is before the image is pushed: a bad artifact never even leaves the local machine. All those tsc, clippy, and lint layers are more and more formal, but the two times the site actually got taken down, it was these thirteen lines that stopped it.

How to review AI output

Two examples from over there left a deep impression. One was a deliberately adversarial review after a big AI rewrite, which in one go surfaced a dozen confirmed defects: server-side request forgery, where a configurable address got fetched directly by the server; a bulk import that wasn’t atomic, so failed records were counted as successes too; a data dashboard that mixed rolling 168-hour windows with calendar-day seven-day windows; cache writes that weren’t tagged, so later reads got stale data. Not a single one of these could tsc or lint catch.

Another: a state value was never written by any code, so a multi-step progress bar could never reach the final step—it rendered four circles, but the state advanced at most to the third. Querying production for the number of rows using that value returned 0.

There was also a rather rare one: the requirement was barely described, so the AI made a defensive interpretation and even wrote in the commit message, “if later specs don’t match this interpretation, this change amounts to an unrelated action.” That’s rarer than getting it right~

There are also cases in my own repos that were rescued by human review. In acg-site's c2193c3: a single PR changed the local-dev fallback port from :3000 to :4000, but the other 8 occurrences of .env.example within the same PR still said :3000. The verdict was “dirty changes committed along the way”; reverting kept the whole repo consistent.

The repo where AI accounts for 80% does it more carefully: multiple perspectives independently review the same code, and the output is a numbered, graded list (H1/M1/L1). The conclusion isn’t binary pass-or-fail either; there’s a go-with-notes tier—mergeable, but these items need follow-up. What it catches are all timing issues that lint can’t reach: check-then-write races overwriting each other under concurrency, effect re-runs clobbering unsaved edits, optimistic updates failing without rollback.

The flip side is right here too: this whole process can’t be found anywhere in the repo—no persistent rules file, no CI job, no agent definition. It lives only in a few commit messages. No matter how rigidly structured they are, how many “Lesson:” sections and reproduction commands they include, the next session only gets them if it happens to dig through git log.

A few side effects of parallel worktrees

In thdl, git worktree list shows three lines: the main repo is on main, and the other two are .claude/worktrees/heuristic-bardeen-567381 and .claude/worktrees/sweet-poincare-f3b7bc. The random-background feature was built in one of them. Handy, but there are three side effects.

A worktree is a full checkout, so lint and formatters will scan it

acg-site's eslint.config.mjs:22-25 just adds it to the ignore list:

// IDE local history".history/**",// Claude Code worktrees".claude/**",

biome.json's files.includes excludes it the same way. Without that, running lint once means scanning the same code twice…

Multiple lockfiles make the bundler pick the wrong workspace root (worktrees are only one cause)

bbps’s 449d72b3 added turbopack: { root: process.cwd() } to next.config.ts, with the comment “avoid Turbopack root inference warnings when there are multiple lockfiles”—at that point it had nothing to do with worktrees. home’s 54b4590 hit the same class of problem but in the opposite direction: it had to stop Next from inferring the workspace root from a pnpm-lock.yaml in the parent directory. Worktrees are just one more source.

Easy to commit by mistake

home once committed a subdirectory under .claude/worktrees/ as a gitlink, dragging in 12 .history/ files and a .env along with it—a classic byproduct of git add -A, with not a word about it in the commit message. Later .history was added to .gitignore, but gitignore doesn’t untrack already-tracked files, so that batch is still sitting in the repo to this day. What the hell—I tell myself every time not to use -A…

So remember to add worktree directories to .gitignore and the various ignore lists at the same time; miss one and it’s a trap~

In the end, none of this is a code problem—it’s all about who reads what and who can touch what. No matter how many tools there are, these two things still have to be decided by a human~

The same AI makes completely different mistakes on each of the three—that surprised me quite a bit… On Prisma it writes “the correct way from the previous major version”; on Drizzle it gets stuck on types and API signatures; on raw SQL it has no idea what limitations that driver has.

Here I’ll note down a few fallback practices I use along the schema-to-migration chain—just notes for myself.

A few spots in Prisma 7 where AI is guaranteed to write it wrong

The CLAUDE.md:18-25 in that acg-site repo has a section literally titled “Key Version Differences (Common AI Mistakes)”. Of the six bullets, only one is Prisma-related:

The Prisma 7 generator is "prisma-client" (not "prisma-client-js"), import path @/generated/prisma/client

One bullet crammed in two things. The ❌→✅ comparison table at the end of .cursor/rules/library-versions.mdc in the same repo splits it into items 3 and 4, writing it out separately again (that repo maintains three sets of convention files at once—I did the cost accounting for writing it that way in the post about convention files, so here I’ll only pick the data-layer-related ones).

It looks redundant, but it’s actually very necessary. Because these two things aren’t a case of “AI can’t do it” but of “AI remembers the old one”.

If you don’t hard-code it, it will guess from memory 100% of the time—it never fails.

I’ll add one of my own: since Prisma 7, the connection string moved from the schema to prisma.config.ts, and the validation in that file is usually written to throw unconditionally.

That’s how prisma.config.ts:5-8 in vns-next looks:

const url = process.env.DATABASE_URL;if (!url) {  throw new Error("DATABASE_URL is not defined");}

The consequence is that during the Docker build you must feed in a placeholder value, even though prisma generate never connects to a database at all—that’s where those two lines of SKIP_ENV_VALIDATION=1 plus a fake connection string in the image come from; I pasted the original text in the self-hosting post.

What you need to note is the direction of causality: the Dockerfile isn’t written wrong—it’s the unconditional throw in prisma.config.ts that ropes the build phase in too.

Any library that does validation at the top level of a config file has this problem; Prisma is just the one I ran into recently.

These all fall under “the training data has the old syntax”. Writing them into CLAUDE.md is the highest-value kind of convention—one line saves you half an hour.

db push can’t create native SQL indexes

This pitfall isn’t the AI’s fault, but the AI won’t proactively warn you about it either.

The search in vns-next uses the pg_trgm extension plus three GIN indexes: fuzzy title, alias array containment, fuzzy tag name. prisma db push won’t create any of these for you—it only syncs what can be expressed in the schema.

So I put them separately in a scripts/db/indexes.sql, with the first line of comments at the top reading “Prisma schema cannot declare trgm/expression indexes; run manually after db:push”.

More importantly, how to verify. The line recorded in the body of commit 35659c4 is “pg_trgm search (EXPLAIN verified index usage)”.

A query running successfully doesn’t mean it used the index—a full table scan also returns correct results, just slowly. For this kind of thing you have to look at the execution plan, not at whether the endpoint returns 200.

A few friction points on the Drizzle side

The thdl side uses Drizzle + postgres.js, and the friction points are a whole different batch.

Connection pool

Dev hot reload keeps creating new connections over and over and leaking them all; you have to attach a globalThis singleton.

This is a pitfall very familiar to Prisma users; switching to Drizzle you still have to hand-write it once (src/lib/db/index.ts:8-13):

declare global {  var __thdl_pg: ReturnType<typeof postgres> | undefined;}const client = globalThis.__thdl_pg ?? postgres(connectionString, { max: 10 });if (process.env.NODE_ENV !== "production") globalThis.__thdl_pg = client;

Enum columns meet searchParams

What comes up from the URL is always string, while the pgEnum column is a union of 9 literals—there’s no clean conversion path in between.

In the end the code was written like this (src/app/(site)/resources/page.tsx:21):

cat ? eq(resources.category, cat as "music") : undefined

It just picks an arbitrary member and casts to it. It works, but it throws away the validation responsibility entirely; to actually do it properly you’d have to pass it through zod’s enum first.

I’ll jot this down for now, haven’t touched it…

Version differences again

The second parameter of Drizzle’s table definition changed starting from 0.36 to return an array instead of an object. thdl has 0.45.2 installed; see src/lib/db/schema.ts:113-117 for the syntax:

(t) => [  index("resources_status_created_idx").on(t.status, t.createdAt),  index("resources_category_idx").on(t.category),]

The AI will most likely write it as => ({ ... }) for you—same nature as those two Prisma points. When checking the changelog, remember not to look at the wrong version; you won’t find this one in 0.45.

And one more that’s not a code problem

What I run locally is pnpm db:push; the steps the README gives everyone else are also pnpm db:push; and in the drizzle/ directory there’s still just one baseline migration to this day.

package.json:14 does define db:migrate, but grepping the whole repo turns up no call site. The deploy side is even more blunt: deploy/ contains nothing but a Caddyfile and a systemd unit, ExecStart is just node server.js, and the database is never touched at all.

In other words, there’s no versioned record of how the schema evolved step by step; it all depends on push aligning things on the spot.

The database is still small, so pushing all at once really is fine for now. But once the table structure gets complicated, or a second person actually has to deploy a copy, that debt comes due… I know it, I just haven’t gotten to it yet.

Wiring the ORM and the auth library takes manual alignment

thdl uses better-auth’s drizzleAdapter, which expects four tables: user / session / account / verification.

But the table names in your own schema aren’t necessarily those, so you have to map them by hand (src/lib/auth.ts:8-16):

database: drizzleAdapter(db, {  provider: "pg",  schema: {    user: schema.users,    session: schema.sessions,    account: schema.accounts,    verification: schema.verifications,  },}),

The AI doesn’t get this wrong because it’s dumb, but because it has no way to know out of thin air what your tables are called. This is exactly the kind of part where a human has to pin things down first and only then let it do the wiring.

A fossil worth mentioning in passing: the allowlist in that repo’s .claude/settings.local.json has two commands back to back — delete the old auth library’s catch-all route directory, create the new auth library’s catch-all route directory.

An entire library swap got recorded in full like that, and in the end the route file is only 4 lines long. Hilarious.

Migration scripts must be idempotent, and they need unit tests

When vns-next migrated from the old Hugo site to Postgres, the first line of the header comment in scripts/migrate-content.ts states the strategy: “Idempotent and re-runnable: upsert Work/Page by primary key; deleteMany DownloadLink then insert; clear then insert SiteLink/TeamMember/DlEntry.”

If it dies partway through, you just run it again — that premise made the whole migration far easier.

I pulled the parsing logic into a standalone module, scripts/lib/parse.ts, with 31 test cases across 6 describe blocks; the acceptance line in the body of commit 35659c4 is simply “all 31 tests green.”

The scariest thing in data migration isn’t a crash, it’s a silent error. A field shifted out of place, a date off by a day — everything runs green and you still can’t see it. Pure functions plus unit tests are the only thing holding the line.

The timezone pitfall deserves its own section. The default schema in js-yaml parses a timezone-less string like date: 2024-07-31 03:56:40 straight into Date, computed as UTC, and the timezone is wrong right there.

The fix is to switch to JSON_SCHEMA so it stays a string, then parse it yourself with +08:00. The comment in scripts/lib/parse.ts:12-13 reads:

js-yaml is a dependency of gray-matter, so we reuse it directly here.
Using JSON_SCHEMA keeps date: 2024-07-31 03:56:40 as a string (the default schema parses it into a Date as UTC, which gets the timezone wrong)

The record counts need to be checkable too. After the migration, the body of commit 35659c4 recorded work=145 / tag=247 / download_link=2307 / page=22 / dl_entry=89.

deploy/README.md:35 picked the first three and wrote them into the import notes, with a verification SQL given separately on line 48: after import, select count(*) from work should be 145. With that one line, re-running it on another machine feels safe.

One last point that’s easy to overlook: encode/decode functions shared between migration scripts and the frontend must be pulled out into a zero-dependency module.

The header of vns-next’s src/lib/download-label.ts:1-3 says:

/** * DownloadLink.label 的编码/解码 —— 纯函数、零依赖 *（迁移脚本与前端共用；不要在这里引入任何 node/解析库依赖） */

It started with commit 404a769: “extract splitLabel into a zero-dependency module to keep gray-matter out of the client bundle.”

Once a shared function casually imports a parsing library, it crawls all the way into the client bundle through the import chain, and nothing can stop it.

When you don’t use an ORM

Another project skipped the ORM entirely and just writes raw SQL through a serverless Postgres HTTP driver.

The complexity you save gets handed straight back to your migration scripts:

• That driver executes only one statement at a time, so the migration script has to implement its own semicolon-splitting state machine, and also handle dollar-quoted blocks and semicolons inside strings
• Bulk writes must be combined into a single unnest upsert. Under an HTTP driver every statement is a separate network round trip, and once the row count grows the latency gets ugly
• Migrations use plain filename ordinals and re-run in full every time, relying on the SQL being idempotent — there isn’t even a migration state table

That last one is actually the most worry-free. With no state table, there’s no “state table doesn’t match the real schema” problem — the hardest kind to track down.

A few habits I have now

That’s it for now — I’ll add more next time I switch ORMs~

The one I moved out

home is my personal homepage repo. The stack’s evolution went like this:

The timing is pretty funny: only 31 minutes between retiring Nuxt and upgrading to Next 16 — two big moves in the same session; and then 22 days later I overturned one of them… impulse is the devil.

Before moving to Vite I did a count:

# 1. src 下所有 tsxfind src -name "*.tsx" | wc -l          # 20# 2. 其中带 use client 的grep -rl "use client" src --include="*.tsx" | wc -l   # 19

20 tsx files, 19 of them starting with "use client"… The only Server Component was src/app/layout.tsx — it exported metadata and viewport, wired up Inter via next/font, mounted three preconnect, rendered the html/body shell and the Toaster — it did a lot, but none of it required RSC.

Now look at output: 'export'. This site had been a static export since Next 15; before the move, next.config.ts looked like this:

import type { NextConfig } from "next";import { fileURLToPath } from "node:url";import { dirname } from "node:path";const nextConfig: NextConfig = {  output: "export",  reactStrictMode: true,  trailingSlash: false,  images: { unoptimized: true },  turbopack: {    root: dirname(fileURLToPath(import.meta.url)),  },};export default nextConfig;

With that choice, SSR / ISR / Route Handler / middleware / next/image optimization were all off, leaving just file routing, the Metadata API, and next/font. For a single-page homepage: routing is useless, meta can just be hardcoded in index.html, and swapping the font for a system stack is something nobody would notice… so why keep it at all?

The ledger after the migration

The stat for 3075556 was 41 files changed, 902 insertions(+), 1862 deletions(-) — a net reduction of 960 lines.

The config comparison is more telling. What got deleted was next.config.ts(15) + src/app/layout.tsx(69) + next-env.d.ts(6) + serwist.config.js(18), 108 lines total; what I got in return was index.html(45) + src/main.tsx(23) + vite.config.ts(30), 98 lines total. About the same line count, but I can understand the latter at a glance.

Most component diffs were just deleting those two lines at the top:

--- a/src/components/app-footer.tsx+++ b/src/components/app-footer.tsx@@ -1,5 +1,3 @@-"use client";- import { useEffect, useState } from "react";

At that point vite.config.ts was 30 lines; later I trimmed it down to just 14:

import { defineConfig } from "vite";import react from "@vitejs/plugin-react";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [react(), tsconfigPaths()],  server: {    port: 3000,  },  build: {    target: "es2022",    sourcemap: false,  },});

The clearest illustration is the runtime stage of Dockerfile:

FROM node:22-alpineRUN npm install -g serveWORKDIR /appCOPY --from=builder /app/dist ./publicEXPOSE 12445CMD ["serve", "public", "-l", "12445"]

Not even Node has to run — just a static file sitting there, the runtime stage is almost boringly clean…

A causal chain I cut along the way

The font chain spans two commits. In the Vite migration commit (3075556), Inter in next/font/google was no longer usable, so I swapped in a local @fontsource package, which suddenly added about 5MB of woff2 for Chinese fonts; ten minutes later in ae004b3 it hit me — the main reason I’d installed PWA in the first place was to cache those 5MB, so I might as well switch to a system font stack (PingFang / YaHei / Roboto), and deleted @fontsource along with the PWA.

“Deleted” isn’t quite accurate though… digging through the log, I found the PWA had already been deleted once back in 5321a54, then reinstalled later — this was the second deletion. So this wasn’t some clean decision at all; it took two rounds of back-and-forth before it settled down.

And deleting a PWA isn’t just deleting code. Old visitors still have the old Service Worker in their browsers, so I had to leave a tombstone SW to let it unregister itself:

// Tombstone service worker.self.addEventListener("install", () => self.skipWaiting());self.addEventListener("activate", (event) => {  event.waitUntil(    (async () => {      const names = await caches.keys();      await Promise.all(names.map((n) => caches.delete(n)));      await self.registration.unregister();      const clients = await self.clients.matchAll({ type: "window" });      for (const client of clients) client.navigate(client.url);    })(),  );});

Clear the cache, unregister, then have already-open pages navigate again… removing a feature is way more hassle than removing code.

The unfinished wrap-up

Then comes the not-so-glorious part. As of today:

• README.md still says Next.js 15 + Serwist + Tailwind 3 + NEXT_PUBLIC_ prefix, but it’s actually Vite 7 + Tailwind 4 + VITE_ — every technical description is wrong
• .github/workflows/build.yml:53's artifact is path: out, while Vite output lives in dist, so whatever CI uploads has long been empty
• The CSS path in components.json points to src/app/globals.css, but the file moved to src/globals.css ages ago
• app-footer.tsx:38's suppressHydrationWarning is dead code — there’s no hydration at all anymore

The funniest part is that 0e83f8c, the time I took Nuxt offline, the commit body actually listed a complete “5 things you have to change along with the framework swap”: Dockerfile, vercel.json, GitHub Actions artifact path, .dockerignore, README… The checklist wasn’t wrong by a single word — the next migration just didn’t follow it, and I didn’t bother to look either.

One more: while cleaning up for e6b5d81 I found @radix-ui/react-slot and class-variance-authority, two dependencies installed by the shadcn scaffold — installed 4-21, deleted 5-14, zero imports across 23 days (there’s no button.tsx in the project at all); .vscode still recommends Vue.volar, leftovers from two frameworks ago. Adding a dependency takes a second; deleting one takes three weeks…

The one that moved in

On the other side is vns, a Galgame resource site. In the same repo you can see the full three-stage evolution: the old branch is Hexo 8.1.1 + NexT, dev/beast is Hugo Extended, and over on vns, the dev server in .claude/launch.json points straight at the neighboring vns-next directory running bun run dev — two repos migrating side by side for comparison.

There were three reasons to move it into Next.js.

First, a static site has no server, so API keys can only sit in plaintext in the frontend JS. At the time, main.js had this One API key just lying there:

const API_URL = "https://example.com/v1/chat/completions";const API_KEY = "sk-xxxx";  // 就这么明文躺着

That’s the only option for AI features on a pure static site — no choice. The same thing in Next.js can go into a Route Handler and the key stays server-side. Also, remember to rotate any key that has been in a public repo; changing the code doesn’t count…

Second, this site’s “database” is 6 JSON files under data/. Ad slots, friend links, download sources, translation groups — all fake databases read at build time. Changing one row of data meant rebuilding the whole site and re-pushing the deploy branch, and that branch is 27.9MB / 1832 files… all to change one line of JSON.

Third, to create a “dynamic feel” I’d piled up over two thousand lines of client JS. main.js was 2347 lines before splitting, stuffed with swup page transitions, lazy loading, counter animations, localStorage toggles, SSE streaming requests. Later it was split into 8 ES modules and the main file dropped to 613 lines, but the pitfalls along the way were pretty typical (these are all on the dev branch):

• 4842e804e: after splitting into ES modules, top-level variables like VALINE_CONFIG stayed in the original file. Module top-level scope doesn’t span files, so the comment component never initialized — and it was users who reported it
• 187ad71b4: a single try/catch wrapped all the inits, so one crash mid-way killed everything after it. Users reported “comments and TOC are both broken” — the TOC was purely collateral damage. Changed to an independent catch per [name, fn]
• d83c2801a: main.js runs before the DOM as a render-blocking script, so getElementById returns null; swup transitions also caused the global click handler to be bound repeatedly, finally bailed out with a window._fireworkBound flag

All of these are things a component lifecycle gives you for free; hand-rolling means hitting them one by one.

One more thing that’s easy to forget: URLs have to be preserved exactly… Hexo’s abbrlink short link (crc16/dec, permalink is p/:abbrlink/) became a Hugo slug, then became work.id on the new site — /p/{id}/ survived three generations of that old link. Not even the trailing slash can change — Artalk/Valine historical comments are stored under the path /p/{id}/ with the slash, and missing one character means losing comments. To that end, vns-next had to disable the framework’s built-in trailing-slash redirect and take over itself; I posted the full comments from that tug-of-war in the post about convention files.

Finally, one intermediate state. The bbps site is also output: 'export', with next.config.ts only 12 lines, and real-time data simply bypassed with client-side polling:

useEffect(() => {  fetchStats()  const id = setInterval(fetchStats, 30000)  return () => clearInterval(id)}, [fetchStats])

Hit an external API every 30 seconds — good enough… Static shell + client polling, effortless.

A month of moving things around, and it really boiled down to one question: is there anything on this site that absolutely has to live on a server? Think it over and the answer is obvious—there’s no mystery to it. Anyway, I’m out~

{{ div (div (.Plain | htmlUnescape | strings.RuneCount) 2) 60 }}

• ReadingTime
• Plain
• strings.RuneCount
• math.Div

bszCaller.fetch(  "//busuanzi.ibruce.info/busuanzi?jsonpCallback=BusuanziCallback",  function (a) {    bszTag.texts(a);    bszTag.shows();  });

I recently set up a dual-boot system on my computer and switched my main system to the Arch Linux distribution. Here are some commands I commonly use, for the record.

Linux

# 摧毁所有sudo rm -rf /*# 将 base64 字符解码后通过管道执行到 zsh 内摧毁所有echo "c3VkbyBybSAtcmYgLyo=" | base64 -d | zshls testpwdcat test.ccd testcp test.c test.cpprm test.cmv test.c test.cppmkdir testsudoping google.comdf -h

Arch

fastfetch | lolcat

pacman

pacman -S linuxpacman -Ss linuxpacman -Syupacman -Rns linuxpacman -Qi linuxpacman -Rns $(pacman -Qtdq)pacman -Qs linuxpacman -Scpactree linuxpaccache -r

yay

yayyay downgradeyay -Psyay -Yc

systemctl

# 启动服务systemctl start dhcpcd# 停止服务systemctl stop dhcpcd# 重启服务systemctl restart dhcpcd# 重新加载服务以及它的配置文件systemctl reload dhcpcd# 查看服务状态systemctl status dhcpcd# 设置开机启动服务systemctl enable dhcpcd# 设置服务为开机启动并立即启动这个单元systemctl enable --now dhcpcd# 取消开机自动启动systemctl disable dhcpcd# 重新载入 systemd 配置。扫描新增或变更的服务单元、不会重新加载变更的配置systemctl daemon-reload dhcpcd

Usage

<link rel="stylesheet" href="https://registry.npmmirror.com/weblive2d/latest/files/waifu.css"><script async src="https://registry.npmmirror.com/weblive2d/latest/files/js/autoload.js"></script>

# Define custom file paths.# Create your custom files in site directory `source/_data` and uncomment needed files below.custom_file_path:  #head: source/_data/head.njk  #header: source/_data/header.njk  #sidebar: source/_data/sidebar.njk  #postMeta: source/_data/post-meta.njk  #postBodyStart: source/_data/post-body-start.njk  #postBodyEnd: source/_data/post-body-end.njk  #footer: source/_data/footer.njk  #bodyEnd: source/_data/body-end.njk  #variable: source/_data/variables.styl  #mixin: source/_data/mixins.styl  #style: source/_data/styles.styl  head: source/_data/head.njk

<link rel="stylesheet" href="https://registry.npmmirror.com/weblive2d/latest/files/waifu.css"><script async src="https://registry.npmmirror.com/weblive2d/latest/files/js/autoload.js"></script>

hexo cl; hexo s

# Inject# Insert the code to head (before '</head>' tag) and the bottom (before '</body>' tag)# 插入代码到头部 </head> 之前 和 底部 </body> 之前inject:  head:    # - <link rel="stylesheet" href="/xxx.css">    - <link rel="stylesheet" href="https://registry.npmmirror.com/weblive2d/latest/files/waifu.css">  bottom:    # - <script src="xxxx"></script>    - <script async src="https://registry.npmmirror.com/weblive2d/latest/files/js/autoload.js"></script>

hexo cl; hexo s

Source Code

The source code of the CDN service used in this article comes from here…

GitHub: nova1751/live2d-api

Reproducing this problem is easy. It’s most likely a network issue: just turn off your proxy tool, accelerator, or similar network-optimization software, then make sure the pushing device’s network is within mainland China, and chances are you’ll reproduce it…

Solving the Problem

These problems are usually caused by an unstable network environment, so start with the network. First, use a network proxy tool to relay the current device’s network environment—relay the resources Hexo pushes to another device, and send them to GitHub from that device.

0x0001

I personally use Clash as the proxy medium; check the proxy port.

Note down this port 7890. If you’re using v2ray proxy, the default port is usually 1080.

0x0002

Use the following command in the terminal to change git's global proxy settings

git config --global http.proxy http://127.0.0.1:7890

--global means global, 127.0.0.1 means the local machine, and 7890 refers to the proxy port you noted down earlier.

0x0003

Change the push address to an https address. You can go to your GitHub repository, click “Code>HTTPS” and copy it.

Then edit the _config.yml configuration file in your Hexo site’s root directory to change the push address.

If you were already using an https address rather than ssh, you can skip this step.

0x0004

Then it’s the Hexo trio! Check whether the push succeeded.

hexo cl && hexo g && hexo d

Don’t forget to enable your proxy tool.

When I first saw the buttons in the announcement bar of the Butterfly theme’s official documentation, I didn’t think much of it. But once I had a use for them, I kept wanting to add buttons to my own blog’s announcement bar. I searched the theme’s official docs from top to bottom, but they never explained how to do it. Once I realized this wasn’t a built-in feature of the theme, I planned to search for ready-made mods that others had shared, but I never could find any — maybe I just wasn’t looking hard enough (. So I wrote one myself, modeled on the style in the official docs. It uses only HTML and CSS, so it’s pretty simple.

Tutorial

0x0001

Open the Buitterfly theme config file _config.butterfly.yml, and add the following HTML code to the card_announcement: option under aside (the sidebar). Pick the snippet with however many buttons you need.

1 button

<div class="social-button"><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第一个按钮，填自己的内容</a></div>

2 buttons

<div class="social-button"><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第一个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第二个按钮，填自己的内容</a></div>

3 buttons

<div class="social-button"><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第一个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第二个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第三个按钮，填自己的内容</a></div>

4 buttons

<div class="social-button"><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第一个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第二个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第三个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第四个按钮，填自己的内容</a></div>

5 buttons

<div class="social-button"><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第一个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第二个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第三个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第四个按钮，填自己的内容</a><a class="button--animated" href="https://baidu.com/" rel="external nofollow noreferrer" target="_blank">第五个按钮，填自己的内容</a></div>

If you need more buttons, just add more a tags.

0x0002

Replace the links in the href="https://baidu.com/" attribute and the text inside the a tags with your own, using my aside sidebar config as a reference.

# aside (側邊欄)# --------------------------------------aside:  enable: true  hide: false  button: true  mobile: true # display on mobile  position: right # left or right  display:    archive: true    tag: true    category: true  card_announcement:    enable: true    content: 这是一段公告内容。<div class="social-button"><a class="button--animated" href="//qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=aNthm0SgxBnx28iW06K8NQmuT9OYBweY&authKey=6PPWxZgCuCAQ6L7%2BVAAjSK8c%2FMGBUbQEOyliEmhB9njVrJUoOyIaNrta2q992Ok7&noverify=0&group_code=875766458" rel="external nofollow noreferrer" target="_blank">👉 QQ 交流群 👈</a><a class="button--animated" href="//t.me/FullDiveSAO" rel="external nofollow noreferrer" target="_blank">👉 TG 交流群 👈</a></div>

0x0003

Add the following style code to your own custom CSS file.

/* aside公告栏按钮美化 */.social-button .button--animated {  background: #3eb8be;  color: rgb(255, 255, 255);  display: block;  margin: 4px 0;  text-align: center;  line-height: 2.4;  transition: 0.3s;  border-radius: 8px;}.social-button .button--animated:hover {  background-color: #40c4ae;}.social-button .button--animated:active {  background-color: #339ea3;}

0x0004

Finally, run the three Hexo commands and check out the result!

hexo cl; hexo g; hexo s