Add a supported root-domain change flow #12

New Issue

2026-07-28T12:21:44+09:00

FLYEMOJ1 commented

2026-07-28 12:21:44 +09:00

(Migrated from github.com)

问题

根域名在 bootstrap 时定死（FELIS_ROOT_DOMAIN），之后没有任何改它的流程。要换域名，得手工碰六个面，其中只有 login 的 CR 会自收敛：

三个 toml 配置
panel 证书（写一次就不再改）
两个 Secret
Velocity 配置
login 的 MinecraftServer CR

漏掉任何一个，症状是部分功能坏掉而不是整体报错 —— 最难查的那种。

证据

Identified by Claude Opus 5 (claude-opus-5) while mapping what a live domain change would have to touch, on 2026-07-28.

这一条和「Make configuration updates reach already-deployed installs」（issue #1）同源：根域名会渗进已渲染的产物里，而重跑 setup 不会重渲染它们。

另有一个不在代码里的前提条件：DNS 上 *.<domain> 的通配不覆盖 op.console.<domain> —— 那是第三层，必须单独有记录。换域名时这一条最容易漏。

验收

有一条命令或流程，输入新域名，六个面全部收敛，且能验证。

备注

重跑 bootstrap 不是解法。 它会覆盖运维手动调过的东西，包括那张写一次就不动的 panel 证书。

在这条落地之前，至少应该有一份把六个面逐条列出来的手册 —— 现在连清单都散在各处。

## 问题根域名在 bootstrap 时定死（`FELIS_ROOT_DOMAIN`），之后没有任何改它的流程。要换域名，得手工碰六个面，其中只有 login 的 CR 会自收敛： - 三个 toml 配置 - panel 证书（写一次就不再改） - 两个 Secret - Velocity 配置 - login 的 MinecraftServer CR 漏掉任何一个，症状是部分功能坏掉而不是整体报错 —— 最难查的那种。 ## 证据 Identified by Claude Opus 5 (claude-opus-5) while mapping what a live domain change would have to touch, on 2026-07-28. 这一条和「Make configuration updates reach already-deployed installs」（issue #1）同源：根域名会渗进已渲染的产物里，而重跑 setup 不会重渲染它们。另有一个不在代码里的前提条件：DNS 上 `*.<domain>` 的通配不覆盖 `op.console.<domain>` —— 那是第三层，必须单独有记录。换域名时这一条最容易漏。 ## 验收有一条命令或流程，输入新域名，六个面全部收敛，且能验证。 ## 备注 **重跑 bootstrap 不是解法。** 它会覆盖运维手动调过的东西，包括那张写一次就不动的 panel 证书。在这条落地之前，至少应该有一份把六个面逐条列出来的手册 —— 现在连清单都散在各处。

Lemon-miaow commented

2026-09-26 11:24:50 +09:00

(Migrated from github.com)

6a06185 加了 sudo felis domain set [-yes] <新根域名> 和 sudo felis domain check。

set 先打印计划（每个面从什么改成什么、会作废多少 passkey、没有 SMTP 时如何恢复），加 -yes 才动手。执行顺序：两份 toml → panel 证书（Felis 自签的重签，旧证书留作 *.pre-domain-<时间>；运维自己的证书若不覆盖新名字，在改动任何东西之前就停下）→ 两个命名空间的 felis-config 与 felis-api-tls Secret → login 的 CR env → 代理的 felis-link.properties → 滚动 felis-api → 重启 felis-velocity → 等 login pod 带新 env 就绪 → 跑 check。在 [auth] 里手动设的主机名保留不动。重复执行只收敛还落后的面。
check 每个面输出一行（包括 Cloudflare tunnel ingress 和 DNS，并单独提示通配记录不覆盖 op.console），有面落后时退出码为 1。

安装器（23b7c14）：重跑时保留 [auth]。已安装的主机若带了不同的 FELIS_ROOT_DOMAIN，安装器在第一步就退出，并提示改用 felis domain set。
54a5331：felis-link.properties 内容没变时不再重写，check 用 mtime 判断代理是否落后因此不会误报。

VM 实测（k3s / CentOS Stream 9）：

10.211.55.6.nip.io → 10-211-55-6.nip.io 用时 34 秒。独立核对了四处：30443 上实际下发的证书 SAN、两个主机名下的 /config.json、代理日志 Felis routing ready: rootDomain=10-211-55-6.nip.io、login pod 的 FELIS_ROOT_DOMAIN / FELIS_PANEL_HOSTNAME，全部是新名字。
第二次 set -yes：所有面都是 already，felis-api pod 和代理启动时间都没变。
用旧的 FELIS_ROOT_DOMAIN 跑安装器：输出第 4 行就拒绝，没有改动任何东西。
不带该变量完整重跑安装器：保留了搬过去的域，check 全部 ok。
切回 10.211.55.6.nip.io：30 秒，check 全部 ok。

测试：Go 单测和 shell 测试逐条做了变异验证（故意改坏被测代码，确认测试变红后再恢复）。
文档：docs/operations.md §6。

6a06185 加了 `sudo felis domain set [-yes] <新根域名>` 和 `sudo felis domain check`。 **set** 先打印计划（每个面从什么改成什么、会作废多少 passkey、没有 SMTP 时如何恢复），加 `-yes` 才动手。执行顺序：两份 toml → panel 证书（Felis 自签的重签，旧证书留作 `*.pre-domain-<时间>`；运维自己的证书若不覆盖新名字，在改动任何东西之前就停下）→ 两个命名空间的 `felis-config` 与 `felis-api-tls` Secret → login 的 CR env → 代理的 felis-link.properties → 滚动 felis-api → 重启 felis-velocity → 等 login pod 带新 env 就绪 → 跑 check。在 `[auth]` 里手动设的主机名保留不动。重复执行只收敛还落后的面。 **check** 每个面输出一行（包括 Cloudflare tunnel ingress 和 DNS，并单独提示通配记录不覆盖 `op.console`），有面落后时退出码为 1。安装器（23b7c14）：重跑时保留 `[auth]`。已安装的主机若带了不同的 `FELIS_ROOT_DOMAIN`，安装器在第一步就退出，并提示改用 `felis domain set`。 54a5331：felis-link.properties 内容没变时不再重写，check 用 mtime 判断代理是否落后因此不会误报。 VM 实测（k3s / CentOS Stream 9）： - `10.211.55.6.nip.io → 10-211-55-6.nip.io` 用时 34 秒。独立核对了四处：30443 上实际下发的证书 SAN、两个主机名下的 `/config.json`、代理日志 `Felis routing ready: rootDomain=10-211-55-6.nip.io`、login pod 的 `FELIS_ROOT_DOMAIN` / `FELIS_PANEL_HOSTNAME`，全部是新名字。 - 第二次 `set -yes`：所有面都是 already，felis-api pod 和代理启动时间都没变。 - 用旧的 `FELIS_ROOT_DOMAIN` 跑安装器：输出第 4 行就拒绝，没有改动任何东西。 - 不带该变量完整重跑安装器：保留了搬过去的域，check 全部 ok。 - 切回 `10.211.55.6.nip.io`：30 秒，check 全部 ok。测试：Go 单测和 shell 测试逐条做了变异验证（故意改坏被测代码，确认测试变红后再恢复）。文档：docs/operations.md §6。

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: FelisMC/Felis#12