第一章 域名耦合点调查

1.1 调查方法:数据库全量扫描 + 代码 grep 扫描

1dao 这套站点经过多年累积,域名 1dao.cc(以及 shop.1dao.cc、blog.1dao.cc、nav.1dao.cc 等子域)散落在数据库表的内容字段、PHP 文件、HTML 文件、JSON 配置、CSS 文件等多个位置。要做一次"无损、可逆、可预览"的整站换域名,第一步必须把所有耦合点摸清楚,否则后续替换必然遗漏,导致站点静态资源 404、接口跨域、DIY 页错乱等问题。

调查分两条腿走:

1. 数据库全量扫描:利用 MySQL 的 information_schema.columns 元数据,把所有可能的字符串类型列(char / varchar / text / mediumtext / longtext / tinytext / json)枚举出来,再逐列用 LIKE '%1dao.cc%' 判断是否含目标域名。
2. 代码 grep 扫描:用 grep -rl 在站点根目录下递归搜索 1dao\.cc,通过 --include 白名单限定文件扩展名,通过 --exclude-dir 黑名单剔除依赖目录。

两条腿缺一不可:数据库侧负责"用户内容"中的耦合(文章正文、DIY 页配置、商品图、主题、配置项值等),代码侧负责"应用代码"中的耦合(模板硬编码、CSS 背景图、PHP 中的绝对 URL、HTML 中的 <a href> 等)。

1.2 数据库调查结果

四个业务库中均存在 1dao.cc 字样,具体分布如下:

#### 1.2.1 crmeb 库(CRMEB 商城)

CRMEB 的耦合点最多,主要集中在以下几个表:

表名	关键列	说明
`eb_system_config`	`value`	`site_url` 配置项,整站根 URL,影响支付回调、商品分享、H5 跳转
`eb_store_product`	`image`、`slider_image`、`description`	商品主图、轮播图、详情图通常存的是完整 URL
`eb_store_category`	`pic`	分类图标
`eb_diy`	`value`	DIY 可视化页面的 JSON 配置,内部含图片、跳转链接
`eb_theme`	`config`	主题模板的配置 JSON
`eb_system_group_data`	`value`	组合数据(广告位、首页 banner)
`eb_article`	`content`、`image_input`	文章正文与封面

#### 1.2.2 emlog 库(博客)

emlog 的耦合点相对集中:

• emlog_options:blogurl 选项,博客整站根 URL,影响 RSS、sitemap、文章分享
• emlog_blog:content 字段中存在相对链接被历史编辑器自动转成的绝对 URL
• emlog_comment:url 字段,评论者填写的个人站点(部分含 1dao.cc 的自评)
• emlog_twitter:碎语内容中可能的内部链接

#### 1.2.3 walle 库(上线部署)

walle 是上线部署系统,耦合点在项目配置:

• project 表:level、server_id 之外的配置列中含目标机器上的部署路径,历史项目记录中绝对路径含 1dao.cc
• record:发布记录中的注释
• task:任务执行上下文

#### 1.2.4 zentao 库(禅道)

zentao 是项目管理系统,耦合点比较多但量级小:

• zt_project:项目描述中的链接
• zt_task:任务描述
• zt_doccontent:文档正文(富文本,含绝对 URL)
• zt_history:操作历史中的变更前后值

#### 1.2.5 汇总

四个库合并扫描后,含 1dao.cc 的列行数总计约 400+ 处。这个量级决定了不可能手工逐条 UPDATE,必须脚本化。其中 CRMEB 占六成以上,emlog 与 zentao 各占一成多,walle 较少。

1.3 代码调查结果

在 /var/www 下递归 grep 1dao\.cc,排除 node_modules、vendor、runtime、cache、.git 等依赖与缓存目录后,共在 24 个文件中发现硬编码。按站点归档:

• 主站 /var/www/1dao.cc/:

- index.html:首页中的导航、footer 链接

- counter.php:计数器脚本中的回调 URL

- about-site/index.html:关于页

- releases/index.html:发布日志页

• 导航站 /var/www/nav/:

- index.html:所有导航项的 href

• 博客 /var/www/blog/:

- header.php:博客头部模板中的 RSS、logo 链接

- style.css:CSS 中 background-image 的绝对 URL

- showcase.php:作品展示页

- export_article.php:导出文章时的链接处理

• walle /var/www/walle/:

- Project.php:项目控制器中的硬编码示例

- help.php:帮助文档

• 其他:crmeb 的 .env、zentao 的 config/my.php 等配置文件

1.4 应用配置层面的耦合

除了"看得见的字符串",还有几处"运行时才生效"的耦合点必须单独处理:

1. CRMEB site_url:写在 eb_system_config 表中,CRMEB 启动时会读入并拼装到支付回调、商品分享等位置。换域名时必须先改它,否则即使其他位置都改了,支付回调依然指向旧域名。
2. emlog blogurl:同上,写在 emlog_options 表中,emlog 在渲染 RSS / sitemap / 文章链接时用它做 base。
3. zentao 运行时检测:zentao 不把域名写在配置文件,而是从 HTTP 请求头 Host 中实时推断,所以只要 nginx 把对应 server_name 配好、Host 头正确,zentao 会自动适配。这一项不需要在数据库或代码中改,但必须保证 nginx 配置先于 zentao 生效。
4. walle 数据库 project 表:walle 把项目部署路径写入 project 表,这条路径是服务器本机路径而非 URL,但如果在 walle 的"项目设置"中填写过完整回调 URL,就需要替换。

1.5 调查脚本

数据库扫描的核心脚本是借助 information_schema.columns 获取所有字符串类型列,再逐列 LIKE 检查:

#!/usr/bin/env bash

## 第二章 `change-domain.sh` 设计

### 2.1 需求

`change-domain.sh` 的核心需求只有一句话:**整站域名替换**,覆盖数据库、代码、缓存三大块。但这一句话拆开看,要求极其严苛:

1. **整站**:不能只改某一站,必须 4 个库 + 24 个代码文件全覆盖。
2. **原子性**:要么全改,要么全不改。不能改到一半挂掉留下"半残站点"。
3. **可预览**:`--dry-run` 必须先告诉用户"我将要动这些表、这些文件",用户确认后再执行。
4. **可细分**:`--db-only` / `--files-only` 让用户能分步操作,先改代码再改数据库,反之亦可。
5. **可逆**:配合 `switch-env.sh` 的快照机制,改完能回滚。
6. **不误伤**:这是最难的,详见 2.2。

### 2.2 核心问题:短域名误伤长域名

这是整条工具链最难的一个问题,需要专门讲清楚。

#### 2.2.1 错误示例

假设要执行 prod → dev 切换,映射关系如下:

| 旧域名 | 新域名 |
|--------|--------|
| `shop.1dao.cc` | `dev.shop.1dao.cc` |
| `1dao.cc` | `dev.1dao.cc` |

如果直接顺序执行 `REPLACE`:

1. 先把数据库中所有 `shop.1dao.cc` 替换成 `dev.shop.1dao.cc`。
2. 再把所有 `1dao.cc` 替换成 `dev.1dao.cc`。

第 2 步会**误伤**第 1 步已经替换好的 `dev.shop.1dao.cc`:因为它内部仍然包含 `1dao.cc` 这个子串,会被替换成 `dev.shop.dev.1dao.cc`,变成了一坨垃圾。

#### 2.2.2 误伤结果

最终结果:

| 原值 | 错误结果 | 正确结果 |
|------|----------|----------|
| `shop.1dao.cc` | `dev.shop.dev.1dao.cc` ❌ | `dev.shop.1dao.cc` ✓ |
| `1dao.cc` | `dev.1dao.cc` ✓ | `dev.1dao.cc` ✓ |

短域名永远会误伤长域名,因为短域名是长子域名的子串。这不是排序能解决的——无论先做长还是先做短,总会出问题:

- 先长后短:长替换的结果里含短,被短再次命中。
- 先短后长:短替换的结果里不含长(因为短还没把长的前缀补上),但短替换之后所有出现 `1dao.cc` 的地方都变成 `dev.1dao.cc` 了,等再做长替换 `shop.1dao.cc → dev.shop.1dao.cc` 时,文本里已经没有 `shop.1dao.cc` 了,长替换完全失效,得到 `shop.dev.1dao.cc` 这种错乱结果。

### 2.3 占位符法

解决上述误伤的标准技术是**占位符法**(placeholder pass),分两阶段:

#### 2.3.1 阶段 1:所有旧域名 → 唯一占位符

为每个旧域名分配一个**不可能出现在任何真实文本中**的占位符串,本工具用 `@@DMNCHG_<idx>_@@` 的格式:

| 旧域名 | 占位符 |
|--------|--------|
| `shop.1dao.cc` | `@@DMNCHG_0_@@` |
| `1dao.cc` | `@@DMNCHG_1_@@` |

**关键点**:占位符不能含任何域名片段,也不能含任何被替换域名的子串。这样后续替换绝不会命中它自己。

阶段 1 按**旧域名长度降序**执行(长的先替换):

UPDATE table SET col = REPLACE(col, 'shop.1dao.cc', '@@DMNCHG_0_@@');

UPDATE table SET col = REPLACE(col, '1dao.cc', '@@DMNCHG_1_@@');

- 第一条把 `shop.1dao.cc` 换成 `@@DMNCHG_0_@@`,此时 `1dao.cc` 这个子串**仅**出现在不是 `shop.1dao.cc` 的位置。
- 第二条把剩下的 `1dao.cc` 换成 `@@DMNCHG_1_@@`。**注意**:已经被换成 `@@DMNCHG_0_@@` 的位置不含 `1dao.cc`,不会被误命中。

阶段 1 结束后,数据库里没有任何 `1dao.cc` 字样了,全部变成了占位符。

#### 2.3.2 阶段 2:占位符 → 新域名

占位符不含任何域名,所以阶段 2 的替换互不影响:

UPDATE table SET col = REPLACE(col, '@@DMNCHG_0_@@', 'dev.shop.1dao.cc');

UPDATE table SET col = REPLACE(col, '@@DMNCHG_1_@@', 'dev.1dao.cc');

无论执行顺序如何,结果都正确。

#### 2.3.3 优势

占位符法的本质是**中转一层**,把"多对多替换"降为"多次一对一替换":

- 多对多:`{shop.1dao.cc, 1dao.cc}` → `{dev.shop.1dao.cc, dev.1dao.cc}`,元素互为子串,无法顺序执行。
- 中转后:`{shop.1dao.cc, 1dao.cc}` → `{占位符0, 占位符1}` → `{dev.shop.1dao.cc, dev.1dao.cc}`,每个箭头都是"原值不含目标值的子串"的安全替换。

这个思路同样适用于代码文件、JSON 配置等所有文本替换场景。

### 2.4 多对映射排序

占位符法阶段 1 必须按旧域名长度降序排序,否则短域名先命中长域名的子串。在 shell 中实现:

第三章 change-domain.sh 实现与调试

3.1 第一版实现

第一版使用经典的 find + xargs + grep 组合搜索文件:

find "${WWW_ROOT}" -type f \
     -not -path '*/node_modules/*' \
     -not -path '*/vendor/*' \
     -not -path '*/runtime/*' \
     -not -path '*/.git/*' \
     -print0 | xargs -0 grep -l '1dao\.cc'

#### bug1:搜索范围错误

现象:dry-run 输出的命中文件清单里出现了若干路径异常:

/root/backup/www-2024-01/index.html
/root/.openclaw/session/xxxx/context.txt
/var/www/...

dry-run 阶段还好,但实际执行时,脚本会按这些路径去 sed -i 修改文件,意味着会改到 /root/backup/ 下的备份文件、改到 agent session 上下文记录文件,留下脏数据。

排查:在脚本里 set -x 跟踪 find 的起始目录参数,发现 WWW_ROOT 在某次手误中被设置为 /(根目录),find 就从根开始扫,自然把所有用户家目录、agent 上下文全扫了一遍。

根因:find 接受任意路径作为起点,且对路径无任何安全校验,即使给 / 也照扫不误。这违反了"严格限定在站点目录内"的安全前提。

修复:改用 grep -rl --include --exclude-dir 直接在 WWW_ROOT 下搜索,把"搜索根目录"参数固定为 WWW_ROOT,且强制校验非空:

WWW_ROOT="${WWW_ROOT:-/var/www}"
[ -d "${WWW_ROOT}" ] || { echo "WWW_ROOT not a dir: ${WWW_ROOT}"; exit 1; }

grep -rl --include='*.php' --include='*.html' --include='*.js' \
        --include='*.css' --include='*.json' --include='*.md' \
        --include='*.tpl' --include='*.env' --include='*.env.*' \
        --exclude-dir=node_modules --exclude-dir=vendor \
        --exclude-dir=runtime --exclude-dir=cache --exclude-dir=.git \
        "${OLD}" "${WWW_ROOT}" 2>/dev/null

grep 只在第一个非选项参数(此处是 ${WWW_ROOT})下递归,绝不会"越界"。同时 2>/dev/null 吞掉权限报错(如某些 root-only 文件),避免误报。

3.2 数据库替换循环

数据库侧的替换循环骨架:

for DB in ${DB_LIST}; do
  # 取出该库下所有字符串列
  mysql -sN -e "SELECT table_name, column_name FROM information_schema.columns
                WHERE table_schema='${DB}'
                  AND data_type IN ('char','varchar','text','mediumtext','longtext','tinytext','json')" \
    | while read -r tbl col; do
        # 阶段1: old -> placeholder (按长度降序)
        for i in "${!OLDS[@]}"; do
          mysql "${DB}" -e "UPDATE \`${tbl}\` SET \`${col}\`=REPLACE(\`${col}\`, '${OLDS[i]}', '${PHS[i]}') WHERE \`${col}\` LIKE '%${OLDS[i]}%'"
        done
        # 阶段2: placeholder -> new
        for i in "${!OLDS[@]}"; do
          mysql "${DB}" -e "UPDATE \`${tbl}\` SET \`${col}\`=REPLACE(\`${col}\`, '${PHS[i]}', '${NEWS[i]}') WHERE \`${col}\` LIKE '%${PHS[i]}%'"
        done
      done
done

#### bug2:CONCAT(table_name,"\t",column_name) 输出字面量 \t 而非制表符

现象:第一版中,我把两列拼成一列输出,期望 \t 是制表符,再用 read tbl col 解析:

mysql -sN -e "SELECT CONCAT(table_name,'\t',column_name) FROM information_schema.columns WHERE ..."

执行后,while read -r tbl col 循环里 tbl 的值变成了类似 eb_system_config\tvalue 的整串,col 永远为空。后续的 UPDATE 语句拼出来的表名是 eb_system_config\tvalue,MySQL 报"表不存在",但被外层 || true 吞掉,导致替换实际上从未执行。

排查:在循环里 echo "tbl=[${tbl}] col=[${col}]",输出:

tbl=[eb_system_config\tvalue] col=[]

确认 \t 没被解析成制表符,而是字面两个字符 \ 和 t。

根因:MySQL 的 SQL 字符串中,转义序列 \t 不是制表符。在 MySQL 默认 SQL 模式下,字符串里的 \t 是两个字符:反斜杠 + t。要让 MySQL 输出真正的制表符,需要 CHAR(9):

SELECT CONCAT(table_name, CHAR(9), column_name) ...

这与 Bash、C、Python 等语言不同——Bash 的 echo -e 和 C 的 "\t" 都把 \t 解释成制表符,但 SQL 字面量字符串中 \ 只是字面反斜杠(NO_BACKSLASH_ESCAPES 模式下尤其明显)。

修复:不拼接,直接 SELECT 两列,让 mysql -sN 的默认列分隔符(制表符)来分隔:

mysql -sN -e "SELECT table_name, column_name FROM information_schema.columns WHERE ..."

mysql 客户端在 -s(silent,无表头框线)和 -N(naked,无列名)模式下,默认列分隔符就是 \t 制表符,完美适配 read -r tbl col 的 IFS 分割。同时省去一个 CONCAT 调用,性能略好。

3.3 dry-run 测试验证

--dry-run 模式下的核心代码:

if [ "${DRY_RUN}" = "1" ]; then
  echo "=== 将受影响的数据库表/列 ==="
  for DB in ${DB_LIST}; do
    mysql -sN -e "SELECT table_name, column_name FROM information_schema.columns
                  WHERE table_schema='${DB}'
                    AND data_type IN ('char','varchar','text','mediumtext','longtext','tinytext','json')" \
      | while read -r tbl col; do
          cnt=$(mysql -sN "${DB}" -e "SELECT COUNT(*) FROM \`${tbl}\` WHERE \`${col}\` LIKE '%${OLD}%'" 2>/dev/null)
          [ -n "${cnt}" ] && [ "${cnt}" -gt 0 ] 2>/dev/null && \
            printf '  %s.%s.%s : %s rows\n' "${DB}" "${tbl}" "${col}" "${cnt}"
        done
  done

  echo "=== 将受影响的代码文件 ==="
  grep -rl --include="${INCLUDES[@]}" --exclude-dir=node_modules \
          --exclude-dir=vendor --exclude-dir=runtime --exclude-dir=cache \
          "${OLD}" "${WWW_ROOT}" 2>/dev/null | sed 's/^/  /'
fi

测试用例:把 1dao.cc → dev.1dao.cc(单对映射,不含子域,只验证流程)。

输出:

=== 将受影响的数据库表/列 ===
  crmeb.eb_system_config.value : 1 rows
  crmeb.eb_store_product.image : 18 rows
  crmeb.eb_store_product.slider_image : 18 rows
  crmeb.eb_store_product.description : 7 rows
  crmeb.eb_diy.value : 4 rows
  ...
=== 将受影响的代码文件 ===
  /var/www/1dao.cc/index.html
  /var/www/1dao.cc/counter.php
  /var/www/nav/index.html
  ...

清单数量与第一章调查结果一致,dry-run 通过。

3.4 实际执行测试

去掉 --dry-run,加 --apply,执行 1dao.cc → dev.1dao.cc 单对替换:

./change-domain.sh --apply mappings/single.txt

执行后,验证三处:

1. eb_system_config 表中 menu=site_url 的 value:

   SELECT value FROM eb_system_config WHERE menu='site_url';
   -- 改前:https://shop.1dao.cc
   -- 改后:https://dev.1dao.cc  ← 这里因为只映射 1dao.cc,shop.1dao.cc 中的 1dao.cc 也被换了,得到 dev.shop → dev.1dao.cc,验证占位符法的必要性

(实际生产用例会同时映射 shop.1dao.cc,此处单对测试目的是验证主流程能跑通。)

1. 代码文件:grep -l dev.1dao.cc /var/www/1dao.cc/index.html 命中。
2. Redis 中 site_url 缓存:FLUSHALL 后再次访问,返回新域名。

主流程验证通过。

3.5 set -euo pipefail 问题

#### bug3:数据库循环中 mysql 对视图表 UPDATE 失败导致脚本退出

现象:脚本头部加了 set -euo pipefail(Bash 严格模式的标准做法, supposedly 防御性编程)。执行到数据库循环时,脚本在某条 UPDATE 后突然退出,后续库与文件均未处理。退出码非零。

排查:set -x 跟踪,发现是某个 UPDATE 语句报错:

ERROR 1356 (HY000): View 'crmeb.V_xxx' references invalid table(s) or column(s) or function(s) or definer/invoker of view lack privilege to use them

原来 information_schema.columns 把视图的列也列出来了。视图本身不能 UPDATE,MySQL 直接报错返回非零退出码。pipefail 把这个非零通过管道传给外层 while,触发 set -e 让整个脚本退出。

根因:set -euo pipefail 是"防御性编程"的常用组合,但在循环体内可能合理失败的场景下会过度敏感。本场景下,视图不能 UPDATE 是预期内的非错误,应该被容忍。

修复:

1. 把 set -euo pipefail 改为 set -u:-u 保留(防变量未定义,这是真错误);-e 去掉(循环中允许失败);-o pipefail 去掉(同理)。
2. 在每个可能失败的 mysql 命令后加 || true,显式声明"这里允许失败":

set -u  # 注意:不再用 -e 和 -o pipefail

mysql "${DB}" -e "UPDATE \`${tbl}\` ..." || true

这是"防御性编程"与"容错性编程"的权衡:-e 适合线性脚本(每步都关键),循环 + 数据库这种"可能合理失败"的场景必须显式容错。

修改后,脚本能跑完所有库、所有表,视图报错被 || true 吞掉,不影响真实表的替换。

---

第四章 switch-env.sh 设计

4.1 需求

switch-env.sh 是在 change-domain.sh 之上构建的"模式管理层",需求:

1. 配置驱动:域名、库列表、快照目录等参数都写在配置文件,不在脚本里硬编码。
2. prod / dev 双向无损切换:从 prod 切到 dev 后,prod 的业务数据(订单、文章、评论)要能保留;切回来时这些数据回来。
3. 首次自动生成:第一次切到 dev 时没有 dev 快照,要用 prod 快照 + 域名替换自动生成。
4. 状态可查:switch-env status 显示当前模式、各快照大小与时间。
5. 快照可更新:switch-env snapshot 把当前模式的最新业务数据固化到快照,避免每次切回都丢失变更。

4.2 设计思路:数据库快照法

#### 4.2.1 为什么不能直接"原地替换"

change-domain.sh 是"原地替换":直接修改当前数据库。它解决的是"换域名",但不解决"切换后如何保留上一模式的数据"。如果 prod → dev 直接原地替换,prod 的业务数据(此时已经被改成了 dev 域名)就丢了 prod 的形态;再切回 prod 时,要么再次原地替换(业务数据已是 dev 期间的新数据,无法回到 prod 形态),要么需要外存。

#### 4.2.2 快照法

为每个模式保存一份数据库快照:

• prod.sql.gz:prod 模式下的数据库全量导出
• dev.sql.gz:dev 模式下的数据库全量导出

切换流程:

保存当前模式快照 → 恢复目标模式快照 → 代码文件替换 → 清缓存 → 更新配置

#### 4.2.3 优势

• 业务数据不丢失:每次切走前都把当前数据存盘,切回来时从盘恢复。
• 双向可逆:从 prod 切到 dev 后,dev 期间产生的数据进入 dev.sql.gz;再切回 prod 时,这些 dev 数据被存盘,prod 数据从 prod.sql.gz 恢复,dev 数据不丢。
• 首次自适应:第一次切到 dev 没有 dev.sql.gz,自动用 prod.sql.gz + 域名替换生成。

4.3 配置文件 env.conf

env.conf 是整个双模式系统的"事实源"(single source of truth):

## 第五章 `switch-env.sh` 实现与调试

### 5.1 第一版实现

第一版直接复制了 `change-domain.sh` 的代码作为内部函数,在 `switch-env dev` 流程中调用。结果首跑就崩了。

#### bug1:`set -euo pipefail` 导致数据库替换循环提前退出

**现象**:`switch-env dev` 执行到数据库替换阶段(从 prod 快照生成 dev 时)直接退出,后续代码替换、清缓存均未执行,留下"数据库已切到 dev 但代码仍是 prod 域名"的半残状态。

**排查**:在脚本头 `set -x` 跟踪,发现退出点在某条 `UPDATE`:

• mysql crmeb -e 'UPDATE v_xxx SET ...'

ERROR 1356 (HY000): View 'crmeb.v_xxx' references invalid table(s) or column(s)...

• ... ← 此处脚本退出

**根因**:`set -euo pipefail` 中,`pipefail` 把管道中任一命令的非零退出码传给最后,`-e` 又捕获这个非零让整个脚本退出。视图 UPDATE 失败是预期内的,但被 `pipefail` 当作真错误。

这跟第三章 3.5 的 bug3 同根,但因为 `switch-env.sh` 直接复用 `change-domain.sh` 内部代码,问题再次出现。

**修复**:同 3.5,把脚本头改为 `set -u`,在 `mysql` 调用后加 `|| true`:

set -u # 不用 -e -o pipefail

mysql "${DB}" -e "UPDATE ..." || true

修复后,`switch-env dev` 能跑完整流程。

### 5.2 数据库替换的 CONCAT 问题

#### bug2:同 3.2 的 CONCAT 问题在 switch-env 内复发

`switch-env.sh` 内部那段"取所有字符串列"的 SQL,最初也写成了 `CONCAT(table_name,"\t",column_name)`,同样输出字面量 `\t`。

**现象**:循环里 `tbl` 拿到 `eb_system_config\tvalue`,`col` 永远空。

**根因**:同 3.2,SQL 字符串中 `\t` 不是制表符。

**修复**:同 3.2,改为 `SELECT table_name, column_name` 两列,让 `mysql -sN` 的默认 tab 分隔符工作。

此处复现完全是因为代码复用时没把 `change-domain.sh` 已修复的版本同步过来。教训:**复制粘贴是 bug 传播的最快路径**。后续把共享的数据库替换逻辑抽成 `lib-domain.sh` 库,两边都 `source` 它,避免再次出现"修了一边忘另一边"。

### 5.3 首次切换测试

测试流程:

1. 在 prod 模式下执行 `switch-env init`。
2. 验证 `prod.sql.gz` 已生成。
3. 执行 `switch-env dev`。

#### 5.3.1 `switch-env init`

第六章 nginx dev 域名配置

6.1 dev-domains.conf

为所有 dev.* 子域配置 nginx server block,文件位置 /etc/nginx/conf.d/dev-domains.conf。这个文件与 prod 的 server block 互斥,不能同时启用同一 server_name,否则 nginx 会随机挑一个 server block 响应。

设计上,prod server block 用 1dao.cc 及其子域 shop.1dao.cc 等,dev server block 用 dev.1dao.cc 及其子域 shop.dev.1dao.cc 等,子域前缀加 dev.,完全分离。

6.2 端口选择:HTTP 80

dev 是测试环境,不需要 HTTPS,直接用 80 端口。这避免了证书申请、续期的运维负担。如果后续 dev 也需要 HTTPS(如测试支付回调),可以加 listen 443 ssl + 自签证书或 let's encrypt staging。

6.3 X-Environment 头

所有 dev server block 加:

add_header X-Environment dev always;

always 关键字让 nginx 在错误响应(4xx、5xx)时也加上这个头,方便从浏览器开发者工具一眼分辨当前访问的是 prod 还是 dev。

6.4 各站 root 配置

完整 dev-domains.conf:

## 第七章 双模式架构总结

### 7.1 prod 模式

- **域名**:`1dao.cc` 及其子域 `shop.1dao.cc`、`blog.1dao.cc`、`nav.1dao.cc`、`zentao.1dao.cc`。
- **HTTP**:`dev-on/off` 机制(本系列第三部分详述)+ letsencrypt 证书,443 端口。
- **业务数据**:真实用户访问的真实数据,严禁破坏。

### 7.2 dev 模式

- **域名**:`dev.1dao.cc` 及其子域 `shop.dev.1dao.cc`、`blog.dev.1dao.cc`、`nav.dev.1dao.cc`、`zentao.dev.1dao.cc`。
- **HTTP**:`switch-env` 切换 + 纯 HTTP 80 端口,无证书。
- **业务数据**:从 prod 快照生成,可在 dev 模式下任意修改测试,不影响 prod。

### 7.3 两种模式的关系

**互斥**:同一份数据库(同一份业务数据)在同一时刻只能用一种模式。因为业务数据中的 URL 字段已经被替换为对应模式的域名,无法"同时支持两种模式"。这是数据库快照法的固有约束。

### 7.4 切换:`switch-env prod/dev`

切换命令:

switch-env dev # prod → dev

switch-env prod # dev → prod

切换耗时主要在 `mysqldump` 与 `mysql` 导入,4 个库共 1.8M 压缩数据,本机 SSD 上总耗时约 5-8 秒,可接受。

### 7.5 文件位置

| 文件 | 路径 | 作用 |
|------|------|------|
| 配置文件 | `/etc/1dao/env.conf` | 模式、域名、库列表、快照目录 |
| 快照目录 | `/var/lib/1dao-env/` | 存放 `prod.sql.gz`、`dev.sql.gz` |
| 工具脚本 | `/usr/local/bin/change-domain.sh` | 单次域名替换 |
| 工具脚本 | `/usr/local/bin/switch-env.sh` | 模式切换封装 |
| nginx 配置 | `/etc/nginx/conf.d/dev-domains.conf` | dev 子域 server block |
| 共享库 | `/usr/local/lib/lib-domain.sh` | 数据库替换的共享函数(待重构) |

完整架构图:

+--------------------------------------------------------+

用户命令
switch-env dev/prod/status/init

+----------------------------+---------------------------+

v

+--------------------------------------------------------+

switch-env.sh
- 读 env.conf
- snapshot_save / snapshot_restore
- 调 change-domain.sh --files-only
- clear_cache_and_reload
- update env.conf CURRENT

+----------------------------+---------------------------+

+-------------------+-------------------+

v v

+--------------------+ +--------------------------+

/var/lib/1dao-env/		change-domain.sh
prod.sql.gz	<----恢复---	- 占位符法
dev.sql.gz	<----保存---	- 数据库全类型覆盖

+--------------------+ | - 文件扩展名白名单 |

- 排除目录黑名单

+-----------+--------------+

v

+--------------------------+

/var/www/*
代码文件 (24 个)

+--------------------------+

v

+--------------------------+

缓存清理
redis FLUSHALL
rm runtime/* cache/*
reload php-fpm nginx

+--------------------------+

v

+--------------------------+

nginx dev-domains.conf
listen 80
X-Environment: dev

+--------------------------+

---

## 第八章 经验教训

### 8.1 占位符法是批量替换的核心技术

字符串批量替换的核心难题是"互为子串的多对映射"。占位符法通过"中转一层"把多对多降为多次一对一,从根本上消除了误伤。这个思路不仅适用于域名替换,还适用于:

- API 版本号替换:`v1 → v2`
- 数据库表前缀替换:`eb_ → mall_`
- 文件路径迁移:`/var/www/old → /var/data/new`

只要满足"原值集合与目标值集合存在子串关系",就该用占位符法。**直接顺序替换必翻车**,这是工程经验,不是理论推导。

### 8.2 `CONCAT` 的 `\t` 字面量陷阱

SQL 字符串中 `\t` 是字面量两个字符,不是制表符。这与 Bash、C、Python 截然不同:

| 语言 | `"\t"` 的含义 |
|------|---------------|
| Bash | 制表符(经 `echo -e` 或 `$'...'`) |
| C | 制表符 |
| Python | 制表符 |
| **MySQL SQL 字符串** | **字面量 `\` + `t`**(默认模式) |

要在 MySQL 中输出真正的制表符:

- `CHAR(9)`:显式字符函数,无歧义。
- 让 `mysql -sN` 客户端用默认列分隔符:直接 `SELECT col1, col2`,客户端自动用 `\t` 分隔多列输出。

后者更简洁,且省一次 `CONCAT` 调用。本工具采用后者。

延伸陷阱:同理,`\n`、`\r` 在 SQL 字符串里也是字面量,不是换行。要从 SQL 输出换行,用 `CHAR(10)`、`CHAR(13)`。

### 8.3 `set -euo pipefail` 在循环中的陷阱

`set -euo pipefail` 是"严格模式"标准做法,适合**线性脚本**:

- `-u`:变量未定义即报错。绝大多数场景都该开,防止拼错变量名静默通过。
- `-e`:命令失败即退出。适合"每步都关键"的线性流程,失败应该立刻终止避免后续在错误状态上继续。
- `-o pipefail`:管道中任一非零退出码传到最后。配合 `-e`,让 `cmd1 | cmd2` 中 cmd1 失败也能被捕获。

但在**循环体内可能合理失败**的场景,这套组合会过度敏感:

set -euo pipefail

for x in $items; do

cmd $x # 某些 x 会让 cmd 失败,但这是预期的

done

附录 A:change-domain.sh 关键函数完整代码

#!/usr/bin/env bash
set -u

CONF_FILE="${CONF_FILE:-/etc/1dao/env.conf}"
WWW_ROOT="${WWW_ROOT:-/var/www}"
DB_LIST="${DB_LIST:-crmeb emlog walle zentao}"

DRY_RUN=0
DB_ONLY=0
FILES_ONLY=0
APPLY=0
MAP_FILE=""

parse_args() {
  while [ $# -gt 0 ]; do
    case "$1" in
      --dry-run) DRY_RUN=1; shift ;;
      --db-only) DB_ONLY=1; shift ;;
      --files-only) FILES_ONLY=1; shift ;;
      --apply) APPLY=1; shift ;;
      --www-root) WWW_ROOT="$2"; shift 2 ;;
      --db-list) DB_LIST="$2"; shift 2 ;;
      -h|--help) usage; exit 0 ;;
      *) MAP_FILE="$1"; shift ;;
    esac
  done
  [ -n "${MAP_FILE:-}" ] || { echo "need MAPPING_FILE"; exit 1; }
}


## 附录 C:常用命令速查

附录 D:故障排查

D.1 切换后访问 dev 域名仍跳到 prod

原因:nginx 没把 dev server block 加载,或 prod server block 的 server_name 与 dev 冲突。

排查:

nginx -T 2>&1 | grep -A2 server_name
curl -sI dev.1dao.cc | grep -i 'x-environment\|server:'

修复:nginx -t 验证配置,systemctl reload nginx 重载。

D.2 切换后站点访问 500

原因:数据库切换成功但代码文件没切,或反之。

排查:

switch-env status  # 看 CURRENT
grep -l dev.1dao.cc /var/www/1dao.cc/index.html  # 看代码是否切
mysql crmeb -e "SELECT value FROM eb_system_config WHERE menu='site_url'"  # 看数据库是否切

修复:用 change-domain.sh --apply 把对应方向补一次。

D.3 切换后 Redis 数据仍指向旧域名

原因:clear_cache 没执行或 Redis 没连上。

排查:

redis-cli ping  # 应返回 PONG
redis-cli keys '*site_url*'  # 看是否还有旧值

修复:redis-cli FLUSHALL,然后 systemctl reload php-fpm。

---

结语

change-domain.sh 与 switch-env.sh 是整个开发测试环境方案的执行核心。前者解决"如何做单次无损替换",后者解决"如何在两种模式间无损切换"。两者结合,加上 dev-on/off(prod 模式下临时开 dev 入口)与 nginx 配置,构成了完整的"prod / dev 双模式架构"。

关键设计决策:

1. 占位符法:消除多对映射的子串误伤。
2. 数据库快照法:实现业务数据的双向无损切换。
3. 配置驱动:env.conf 让方案可迁移、可审计、可测试。
4. grep -rl --include/--exclude-dir:比 find + xargs 更可靠的代码扫描。

关键 bug 教训:

1. SQL CONCAT 的 \t 是字面量,不是制表符。
2. set -euo pipefail 在循环中过度敏感,需 set -u + || true。
3. 复制粘贴传播 bug,共享逻辑应抽库 source。

本系列后续部分将围绕这个双模式架构展开日常运维、监控、CI/CD 集成等内容。

第一章:环境隔离的教训

环境隔离不是"锦上添花"的工程规范,而是"非做不可"的生存底线。1dao 的域名迁移涉及数据库、配置文件、Nginx 站点等多处耦合点,任何一个误操作都可能污染线上数据。本章从线上操作的风险出发,推演到虚拟机隔离的价值,再到 VMware/Docker/Vagrant 三种隔离手段的取舍,最后给出"测试先行"的硬性纪律。

1.1 线上服务器操作的风险

现象描述:在最初评估域名迁移可行性时,曾短暂考虑过直接在生产服务器上跑 change-domain.sh。理由看似合理——"反正改完就能立即生效,免去环境切换的麻烦"。但一旦把 REPLACE 语句、sed -i、Nginx default_server 改动叠加起来,任何一步出错都会立即落到真实业务数据上。

原因分析:线上服务器是"单点且不可逆"的环境。具体风险包括:

• 数据库批量 REPLACE 一旦方向写反(例如把 1dao.cc 替换为 dev.1dao.cc,然后又把刚替换出来的 dev.dev.1dao.cc 再替换一遍),会引发雪崩式脏数据;
• mysqldump 备份如果只做了表结构没做数据,回滚时业务数据彻底丢失;
• Nginx 配置改错后 systemctl reload 失败,整个站点 502,影响真实用户;
• SSH 会话中断时,正在执行的脚本可能留下半完成的中间状态(例如部分表已替换、部分未替换),且无快照可回滚。

解决方案:线上服务器只允许"读"操作和经过测试环境验证过的"写"操作。任何修改类动作,先在镜像测试环境跑一遍完整流程,确认无误后再以"最小变更集"的形式推到线上。

最佳实践:把线上服务器视为只读副本,任何破坏性操作都必须先在隔离环境完成 dry-run 与真实 run 两轮验证。线上操作的每一条命令都应能在测试环境的 shell history 中找到对应记录,确保"已验证"。

1.2 虚拟机隔离的价值

现象描述:在 VMware 虚拟机中搭建的镜像测试环境,在整个迁移过程中被反复 save/restore 了二十多次。每一次"改坏了"都能瞬间回滚到上一个已知良好状态,而宿主机和线上服务器毫发无损。

原因分析:虚拟机隔离提供了四重保障:

1. 零风险:虚机的磁盘是宿主机上的一个文件,任何破坏都局限在该文件内,不会触及宿主系统;
2. 快照回滚:VMware 的 Snapshot 功能可在秒级恢复到任意时间点,等同"游戏存档";
3. 环境一致性:虚机的 OS、PHP、MySQL、Nginx 版本可与线上严格对齐,避免"在我机器上能跑"的悖论;
4. 可移植:虚机文件可整体复制到另一台宿主机或交付给同事,环境随文件迁移。

解决方案:为每一类高风险操作(域名迁移、版本升级、依赖变更)建立独立虚机,操作前打快照,操作失败即回滚。

最佳实践:虚机不是"备选方案",而是高风险操作的"默认载体"。把"先打快照再动手"写成肌肉记忆,成本几乎为零,收益则是规避了不可估量的回滚成本。

1.3 VMware vs Docker vs Vagrant 的选择

现象描述:在选型阶段,曾对比过三种隔离方案,各自的取舍如下表:

维度	VMware Fusion/Workstation	Docker	Vagrant (VirtualBox)
隔离层级	完整硬件级虚拟化	进程级容器	完整虚拟化(封装 VirtualBox)
资源开销	高(独立内核+完整OS)	低(共享宿主内核)	高(同 VMware)
网络模式	NAT/Bridge/Host-only 灵活	bridge/overlay 较复杂	同 VirtualBox
与物理机相似度	最高	最低(无独立内核)	中
快照能力	强(秒级)	弱(需 commit/image)	中(VirtualBox snapshot)
学习曲线	低(GUI 友好)	中(需懂 Dockerfile)	中(需写 Vagrantfile)
适合场景	完整镜像测试环境	微服务/单一进程隔离	团队统一环境分发

原因分析:1dao 是一台运行 Nginx+PHP-FPM+MySQL 的传统 LEMP 单机,迁移操作涉及系统级服务(systemd)、网络配置(bridge IP)、多端口监听。Docker 的容器模型在"系统服务编排"上反而不如完整虚机直观;Vagrant 本质是 VirtualBox 的封装,性能与 VMware 相当但 GUI 体验弱;VMware 在"最接近物理机"这一点上无可替代。

解决方案:主测试环境用 VMware(bridge 模式固定 IP);轻量级的脚本调试(如 change-domain.sh 的纯逻辑测试)可用 Docker 起一个 MySQL 容器快速验证 SQL;Vagrant 仅在需要向团队分发统一环境时考虑。

最佳实践:隔离手段的选择服从于"被隔离对象"的形态——整机关联操作用完整虚机(VMware),单一服务用容器(Docker),团队分发用 Vagrant。不要用一种方案硬套所有场景。

1.4 最佳实践:永远先在测试环境验证,再推线上

把前三节凝结成一条铁律:任何对线上有潜在影响的变更,必须经过"测试环境 dry-run → 测试环境真实执行 → 线上 dry-run → 线上真实执行"四阶段。其中前三个阶段任一失败都不得进入下一阶段。这条规则看似冗长,实则把"不可逆"压缩成了"可逆",是整个迁移工作零事故的根本原因。

---

第二章:域名管理的教训

域名是 1dao 迁移的核心对象,也是踩坑最密集的区域。从 TLD 选择到 HSTS 不可逆性,再到证书 SAN 的覆盖范围,每一条教训都来自真实的故障现场。

2.1 .dev TLD 的陷阱

现象描述:最初计划把开发域名定为 1dao.dev,理由是".dev 一看就是开发环境"。结果 Chrome 一访问就强制跳转到 https://1dao.dev/,并报证书错误——而本地根本没配 .dev 的证书。

原因分析:.dev 是 Google 在 2015 年购买的 gTLD,并于 2017 年起将其加入 Chrome 的 HSTS Preload List,强制所有 .dev 域名走 HTTPS。这意味着:

• 即使在 /etc/hosts 里把 1dao.dev 指向 127.0.0.1,浏览器仍会强制 HTTPS;
• 本地自签证书无法通过 Chrome 的验证(除非手动导入并信任);
• 这个强制行为在浏览器层面,无法通过服务器配置绕过。

## 第三章:浏览器行为的教训

浏览器是最后一个"坑",因为它在用户和服务器之间插入了多层缓存:DNS 缓存、HSTS 缓存、Socket 连接池、Cookie 存储。这些缓存各自独立,任何一层没清干净都会让 hosts 切换"看似失效"。

### 3.1 浏览器 DNS 缓存独立于系统

**现象描述**:改完 `/etc/hosts` 后 `ping dev.1dao.cc` 已经指向新 IP,但 Chrome 仍然访问旧 IP。`dscacheutil -flushcache`、`sudo killall -HUP mDNSResponder` 都试过,无效。

**原因分析**:Chrome 和 Firefox 都有**独立的**应用级 DNS 缓存,与系统 DNS 缓存互不相干。Chrome 的 DNS 缓存默认 TTL 约 1 分钟,但在某些场景下会保留更久(例如已建立的 keep-alive 连接)。

**解决方案**:在 Chrome 地址栏访问 `chrome://net-internals/#dns`,点击 "Clear host cache"。

**最佳实践**:改完 hosts 后,**系统级**和**浏览器级** DNS 缓存都要清,二者缺一不可。

### 3.2 清除浏览器 DNS 缓存

Chrome:

地址栏 → chrome://net-internals/#dns → Clear host cache

Firefox:

地址栏 → about:networking#dns → Clear DNS Cache

Safari:

无独立入口,需重启浏览器或清空全部缓存

**最佳实践**:把 `chrome://net-internals/#dns` 加入书签,作为域名切换后的标准动作之一。

### 3.3 HSTS 缓存

**现象描述**:在清理完 DNS 缓存后,Chrome 仍然把 `http://dev.1dao.cc/` 307 重定向到 `https://`。这是 HSTS 缓存在起作用。

**原因分析**:HSTS 策略存储在浏览器本地的"传输安全状态"表中,与 DNS 缓存是两套独立机制。清 DNS 不会清 HSTS。

**解决方案**:`chrome://net-internals/#hsts` → 在 "Delete domain security policies" 输入 `1dao.cc`(注意是根域名,会连带清除子域名的策略)→ Delete。

**最佳实践**:凡是涉及 HTTPS 切换、域名迁移的场景,清理顺序应是:**DNS 缓存 → HSTS 缓存 → Socket 连接池**,三者依次执行。

### 3.4 Socket 连接池

**现象描述**:DNS 和 HSTS 都清完,Chrome 偶尔还是会"间歇性"访问到旧 IP。抓包发现是某些 keep-alive 连接仍保持着旧的 TCP 会话。

**原因分析**:Chrome 为提升性能,会复用已建立的 TCP/TLS 连接(连接池),这些连接在空闲一段时间内不会关闭。即使 DNS 已经解析到新 IP,旧连接仍走旧 IP。

**解决方案**:`chrome://net-internals/#sockets` → "Flush socket pools"。

**最佳实践**:完整的浏览器缓存清理三件套:`#dns`(Clear host cache)→ `#hsts`(Delete domain security policies)→ `#sockets`(Flush socket pools)。

### 3.5 无痕窗口的价值

**现象描述**:在反复清理缓存的疲惫中,发现一个更省事的方法——直接开无痕窗口验证 hosts 切换。

**原因分析**:无痕窗口启动时使用一个全新的、临时的 profile,DNS/HSTS/Socket/Cookie 缓存均为空。它对 hosts 的解析完全依赖系统当前状态,是"最干净"的验证环境。

**解决方案**:hosts 切换后,优先用无痕窗口验证;确认无误后再处理常规窗口的缓存。

**最佳实践**:**无痕窗口是 hosts 验证的首选工具**。它把"清理缓存"这一易忘步骤直接绕过,是最低成本的验证手段。

### 3.6 Cookie 共享机制

**现象描述**:在 `dev.1dao.cc`(测试)和 `1dao.cc`(线上)同时登录后,发现测试环境的登录态偶尔"串"到线上,或反之。退出一个,另一个也跟着退出。

**原因分析**:Cookie 的作用域由 `Domain` 属性决定,且**不区分端口**:
- 若 Cookie 的 `Domain=.1dao.cc`,则 `1dao.cc`、`dev.1dao.cc`、`1dao.cc:8080`、`1dao.cc:443` **全部共享**;
- 端口不同不会隔离 Cookie(这是 RFC 6265 的设计,出于历史兼容);
- 测试环境与线上同根域名,必然共享 `.1dao.cc` 作用域的 Cookie。

Set-Cookie: session=abc123; Domain=.1dao.cc; Path=/; HttpOnly

第四章:Shell 脚本编程的教训

迁移过程中写了大量 shell 脚本(dev-on.sh、dev-off.sh、switch-env.sh、change-domain.sh),每一个坑都来自真实的调试现场。

4.1 set -euo pipefail 的陷阱

现象描述:change-domain.sh 早期版本头部写着 set -euo pipefail,在循环遍历数据库表做 UPDATE 时,某张视图表报错,整个脚本立即退出,导致后半部分表未替换,数据半残。

原因分析:

• -e:任一命令非零退出即终止脚本。在 for 循环中,一个表的 UPDATE 失败(例如视图不可写)会终止整个循环,后续表全部跳过;
• -u:引用未定义变量报错。有助于发现拼写错误,但在某些动态构造变量名的场景会误伤;
• -o pipefail:管道中任一环节非零则整个管道非零。mysql ... | grep ... | awk ... 中 mysql 对视图 UPDATE 失败会被 pipefail 传播,导致 grep/awk 误判。

## 第五章:数据库操作的教训

数据库是 1dao 域名迁移的主战场,所有教训都围绕"如何在不丢数据、不脏数据的前提下完成批量替换"。

### 5.1 mysqldump --databases 的区别

**现象描述**:迁移前用 `mysqldump db1 db2 > backup.sql` 备份,恢复时 `mysql < backup.sql` 报错 `Unknown database 'db1'`。

**原因分析**:`mysqldump` 是否加 `--databases` 选项,导出内容差异巨大:

| 选项 | 导出内容 | 恢复方式 |
| --- | --- | --- |
| `mysqldump db1 db2 > x.sql` | 仅表结构和数据 | 需手动 `CREATE DATABASE` 后再恢复 |
| `mysqldump --databases db1 db2 > x.sql` | 含 `CREATE DATABASE` 和 `USE` | 恢复时自动建库 |
| `mysqldump --all-databases > x.sql` | 所有库 + 建库语句 | 自动恢复所有库 |

第六章:网络配置的教训

网络是虚机与宿主、测试与线上之间的桥梁,任何一处配置不当都会让"明明改对了"的方案"怎么都不生效"。

6.1 VMware 网络模式

现象描述:虚机最初用 NAT 模式,IP 是 192.168.x.x 动态分配,每次重启可能变化,导致 /etc/hosts 和 Nginx 配置经常失效。

原因分析:VMware 三种网络模式的本质差异:

模式	虚机 IP	与外部网络	与宿主机	适用场景
NAT	动态(vmnet8 DHCP)	经宿主 NAT 出网	可互访	隔离开发,不需固定 IP
Bridge	与宿主同网段独立 IP	直接在局域网	可互访	需固定 IP、需被其他设备访问
Host-only	动态(vmnet1 DHCP)	不可上网	仅宿主可访	纯本地隔离测试

解决方案:开发环境改用 Bridge 模式,在路由器 DHCP 里给虚机 MAC 绑定固定 IP(如 192.168.1.100),从此 IP 永不变。

最佳实践:开发环境用 Bridge 模式 + DHCP 静态绑定,获得固定 IP;NAT 适合临时调试;Host-only 适合纯隔离的安全测试。

6.2 /etc/hosts 与 DNS 解析

现象描述:改完 /etc/hosts 后,ping 立即生效,但 curl 偶尔不生效。

原因分析:域名解析顺序由 /etc/nsswitch.conf(Linux)或 /etc/hosts 优先级(macOS 内置)决定:

## 第七章:版本控制与协作的教训

1dao 的迁移脚本通过 Gitee 组织仓库管理,涉及多账号、权限、敏感信息等典型协作问题。

### 7.1 SSH key 与 Gitee 账号的绑定

**现象描述**:用个人 Gitee 账号的 SSH key push 组织仓库,报 `Permission denied (publickey)`。

**原因分析**:Gitee 的 SSH key 是**账号级**绑定的,一个 key 只能绑定到一个账号。当个人账号未被添加为组织仓库协作者时,push 会被拒。

**解决方案**:多账号场景,用 `~/.ssh/config` 管理多个 IdentityFile:

第八章:文档化的重要性

迁移工作能顺利完成并复用,关键在于每一步都留有文档。本章阐述文档化的具体形态与价值。

8.1 技术文档的价值

现象描述:半年后再次需要切换环境时,凭记忆已经记不清 switch-env.sh 的参数顺序,只能翻 shell history。

原因分析:人脑对操作细节的记忆衰减极快,而迁移类操作低频但高风险,正是"最需要文档"的场景。

解决方案:为每个方案写技术文档,包含三大要素:

• 架构图:整体结构与数据流;
• 使用步骤:从零到可用的可复现命令序列;
• 故障排查:常见错误的诊断与解决。

最佳实践:文档不是"写完就完",而是"有人能用它独立复现方案"——以这个标准衡量文档的完备度。

8.2 文档结构

经过多次迭代,沉淀出以下固定结构:

1. 概述        ← 这个方案解决什么问题
2. 架构        ← ASCII 架构图 + 组件说明
3. 使用步骤     ← 从零到可用的命令序列
4. 命令速查     ← 常用命令一行说明
5. 故障排查     ← 现象 → 原因 → 解决 三段式
6. 维护事项     ← 定期清理、证书续期等

最佳实践:固定文档结构,让读者形成"去第几节找什么"的预期,降低检索成本。

8.3 ASCII 架构图的优势

现象描述:早期文档用图片画架构图,结果图片丢失、版本不一致、无法 diff。

原因分析:图片是二进制文件,版本控制无法 diff,且依赖外部工具渲染。

解决方案:用 ASCII 画架构图:

                    +-----------------+
                    |   宿主机(macOS) |
                    |                 |
   浏览器 ──────────►|  /etc/hosts:    |
   (Chrome)         |  192.168.1.100  |
                    |    dev.1dao.cc  |
                    +--------+--------+
                             │ bridge
                    +--------▼--------+
                    |   VMware 虚机   |
                    |  192.168.1.100  |
                    |                 |
                    |  Nginx:443 ─────► PHP-FPM
                    |     │           │
                    |     ▼           ▼
                    |  MySQL ←── 业务数据
                    +-----------------+

优势:

• 纯文本,版本可控,可 diff;
• 无需任何工具渲染,任何编辑器可读;
• 修改成本极低。

最佳实践:架构图优先用 ASCII;仅在需要表达复杂视觉关系(如时序图)时才用专业工具,并导出文本版本一并入库。

8.4 脚本即文档

现象描述:某些脚本写完后,使用者仍需翻 README 才知道参数。

原因分析:脚本本身没有 --help,所有信息都在外部文档,二者容易脱节。

解决方案:每个脚本内置 --help:

#!/usr/bin/env bash

## 第九章:工作方法论

前八章是"具体教训",本章提炼为"通用方法论",可迁移到任何类似的系统工程任务。

### 9.1 先调查后动手

**教训**:域名替换前若不先全量扫描耦合点,必然漏改。

**方法论**:任何"批量修改"类任务,第一步是**穷举式调查**——用 `information_schema` 扫所有字符串列、用 `grep -rl` 扫所有配置文件、用 `find` 扫所有脚本,把"影响面"先摸清,再动手。

第十章:最佳实践速查表

以下是全书所有最佳实践的分类汇总,可作为日常工作的 checklist。

10.1 环境隔离

#	最佳实践	来源章节
1	线上服务器视为只读副本,破坏性操作先在隔离环境验证	1.1
2	高风险操作默认在虚机进行,先打快照再动手	1.2
3	整机关联操作用 VMware,单一服务用 Docker,团队分发用 Vagrant	1.3
4	变更走"测试 dry-run → 测试执行 → 线上 dry-run → 线上执行"四阶段	1.4

10.2 域名管理

#	最佳实践	来源章节
5	永远不用 `.dev/.app/.page` 等已 preload HSTS 的 TLD 做开发域名	2.1
6	开发域名安全池:RFC 2606 保留 TLD(`.test/.example/.invalid/.localhost`)或真实域名子域名	2.2
7	优先用"现有域名 + 子域名前缀"(`dev./test./local.`),复用通配符证书	2.3
8	开发环境绝不下发 HSTS 头,或 `max-age=0` 主动撤销	2.4
9	证书务必把所有需要的域名写入 SAN,优先用通配符证书覆盖子域名	2.5

10.3 浏览器

#	最佳实践	来源章节
10	改完 hosts 清两遍缓存:系统级(`dscacheutil`/`mDNSResponder`)+ 浏览器级(`chrome://net-internals/#dns`)	3.1/3.2
11	HSTS 缓存独立于 DNS,需在 `#hsts` 单独清除	3.3
12	完整清理三件套:`#dns` → `#hsts` → `#sockets`	3.4
13	hosts 验证首选无痕窗口,绕过所有缓存	3.5
14	测试与线上同根域名时,用双浏览器或独立 Profile 隔离 Cookie	3.6

10.4 Shell 脚本

#	最佳实践	来源章节
15	顶层脚本用 `set -euo pipefail`,容错循环用 `set -u` + `\	\	true`	4.1
16	不要用 `CONCAT` 拼 tab,`mysql -sN` 多列输出天然 tab 分隔	4.2
17	跨平台文件内替换用 `perl -pi -e`,避开 `sed -i` 差异	4.3
18	文件内容搜索优先用 `grep -r --include --exclude-dir`	4.4
19	数组按属性排序:`printf \	awk 加前缀 \	sort \	cut 去前缀`	4.5

10.5 数据库

#	最佳实践	来源章节
20	多库备份必须加 `--databases`,恢复时自动建库	5.1
21	频繁切换的多环境用"快照 save/restore"代替 dump/restore	5.2
22	批量替换始终用占位符法,即使单向替换也要用	5.3
23	不要手动列举表,用 `information_schema.columns` 自动发现字符串列	5.4

10.6 网络

#	最佳实践	来源章节
24	开发环境用 Bridge 模式 + DHCP 静态绑定,获得固定 IP	6.1
25	hosts 修改后 flush 系统 DNS 缓存,再清浏览器缓存	6.2
26	断网时 hosts 解析可能失效,用 IP + `Host` 头直连	6.3
27	`default_server` 影响所有未匹配请求,排查"莫名 444"时优先检查	6.4

10.7 版本控制

#	最佳实践	来源章节
28	多账号用 `~/.ssh/config` 的 Host 别名 + `IdentityFile` 隔离	7.1
29	push 失败先确认:① SSH key 绑定的账号;② 该账号是否在协作者列表	7.2
30	组织仓库用 `git config user.email` 覆盖全局身份	7.3
31	`.gitignore` 第一条是 `.env*`;token 泄露先撤销再清理历史	7.4

10.8 文档

#	最佳实践	来源章节
32	每个方案写技术文档,标准结构:概述→架构→步骤→速查→排障→维护	8.1/8.2
33	架构图优先用 ASCII,纯文本可 diff	8.3
34	每个脚本内置 `--help`,注释解释"为什么"而非"是什么"	8.4

10.9 方法论

#	最佳实践	来源章节
35	先调查后动手:穷举式扫描影响面,产出"影响面清单"再修改	9.1
36	先 dry-run 后执行:破坏性脚本必须支持 `--dry-run`	9.2
37	先备份后修改:`mysqldump --databases` + 虚机快照双保险	9.3
38	小步快跑:改一处→验证→存档,二分定位出错点	9.4
39	重复三次以上的操作写成脚本	9.5
40	配置驱动:可变参数抽到 `env.conf`,脚本读配置	9.6
41	双模式共存:不强求统一,按场景选择	9.7

---

结语

1dao 的开发测试环境搭建,表面是"搭个虚机、改个域名"的工程任务,实质是一次完整的"系统工程方法论"演练。从线上风险的敬畏,到缓存层次的清剿,从 shell 的边界陷阱,到数据库的占位符哲学,每一条教训都来自真实的故障现场,每一条最佳实践都经过反复验证。

这份总结的价值不在于"1dao 这一次怎么做的",而在于它提炼出的 41 条最佳实践可以迁移到任何类似的系统工程任务——无论是下一次域名迁移、版本升级,还是全新项目的环境搭建。把它们作为 checklist,把"先调查、先 dry-run、先备份、小步快跑、工具化、配置驱动"作为肌肉记忆,工程风险就能被压到最低,工程效率就能被拉到最高。

工程能力的本质,不是知道多少命令,而是知道每个命令背后有多少坑,以及如何在动手之前就把这些坑填平。这正是本系列总结想要传达的核心。

第一章:DNS 解析机制深度解析

1.1 DNS 解析层级

当用户在浏览器地址栏输入 dev.1dao.cc 并按下回车,浏览器并不会直接发起 DNS 查询,而是按以下层级顺序逐级查找。理解这一顺序,是排查"为什么改了 hosts 还是不生效"这类问题的前提。

浏览器自身 DNS 缓存
        ↓ (未命中)
操作系统级 DNS 缓存 (macOS 上为 mDNSResponder 维护的缓存)
        ↓ (未命中)
/etc/hosts 文件 (本地静态映射)
        ↓ (未命中)
系统配置的 DNS 服务器 (路由器下发 / 手动设置)
        ↓ (未命中)
递归向上查询根 → 顶级域 → 权威服务器

各层级的特性:

层级	位置	TTL 控制方	清除方式
浏览器 DNS 缓存	进程内存	浏览器策略	`chrome://net-internals/#dns` 清除
系统 DNS 缓存	mDNSResponder 进程	mDNSResponder 内部	`sudo dscacheutil -flushcache`
`/etc/hosts`	文件	手动	直接编辑文件
DNS 服务器	网络侧	zone 文件 TTL	由 DNS 管理员修改

一个常见误区是认为"修改了 /etc/hosts 立刻生效"。事实上,如果系统 DNS 缓存中仍有该域名的旧记录,且 mDNSResponder 没有主动失效该条目,那么 /etc/hosts 的修改可能不会被立即查询到。这与 nsswitch.conf 的解析顺序共同决定了实际行为。

1.2 nsswitch.conf:host 配置行决定解析顺序

macOS 的名字解析服务配置文件位于 /etc/nsswitch.conf(部分 macOS 版本没有该文件,此时采用系统默认顺序)。其中 hosts 行决定了名字解析的来源顺序:

hosts: files dns mdns

含义逐项解析:

• files:优先读取 /etc/hosts 文件。如果命中,直接返回结果,不再向 DNS 服务器查询。
• dns:在 files 未命中后,向 /etc/resolv.conf 中配置的 DNS 服务器发起递归查询。
• mdns:Multicast DNS,主要用于 .local 域名和局域网服务发现(如打印机、AirPlay 设备)。

将顺序改为 dns files mdns 会导致 DNS 服务器响应优先于本地 hosts 文件。这在某些场景下是灾难性的:当你想在本地把 1dao.cc 指向虚机 IP,但公网 DNS 中 1dao.cc 指向线上服务器,且 DNS 服务器返回的 TTL 较长,那么你的 hosts 修改将完全失效。

macOS 默认没有 /etc/nsswitch.conf 文件,但其内部解析模块遵循 files dns 的默认顺序。可通过 scutil --dns 查看实际生效的 DNS 配置上下文:

scutil --dns

## 第二章:HSTS 与 HTTPS 深度解析

### 2.1 HSTS 机制:HTTP Strict Transport Security(RFC 6797)

HSTS 是浏览器端的 HTTPS 强制策略,通过 HTTP 响应头声明:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

各字段含义:

- **max-age**:策略有效期(秒)。浏览器在此期间内,对该域名的所有 HTTP 请求会被自动重写为 HTTPS。本项目中典型值为 31536000(1 年)。
- **includeSubDomains**:策略扩展到当前域名的所有子域名。例如对 `1dao.cc` 设置,则 `dev.1dao.cc`、`admin.1dao.cc`、`api.1dao.cc` 都会受影响。
- **preload**:声明该域名愿意被加入浏览器的 preload list(详见 2.2)。这不是立即生效的指令,需要站长主动到 [hstspreload.org](https://hstspreload.org/) 提交申请。

HSTS 的核心陷阱:**首次访问不生效**。浏览器必须先以 HTTPS 访问过该域名、并收到了带 HSTS 头的响应,才会缓存策略。这就是为什么 HSTS 不能完全替代 301 重定向——首次 HTTP 请求仍可能被中间人劫持。

工作机制时序:

用户访问 https://1dao.cc

↓

服务器返回 200 OK + Strict-Transport-Security: max-age=31536000

↓

浏览器记录该策略,存储在 profile 目录下

↓

后续 1 年内,任何 http://1dao.cc 链接

↓

浏览器内部直接改为 https://1dao.cc (不发起 HTTP 请求)

↓

服务器收到 HTTPS 请求

清除浏览器 HSTS 策略的方法(Chrome):

1. 打开 `chrome://net-internals/#hsts`
2. 在 "Delete domain security policies for domain" 输入框中填入域名(如 `1dao.cc`)
3. 点击 "Delete" 按钮
4. 在 "Query HSTS/PKP domain" 输入框验证是否已清除

### 2.2 HSTS preload list

HSTS preload list 是浏览器厂商维护的、内置在浏览器二进制文件中的永久 HSTS 域名列表。一旦被加入,即使站长删除了 HSTS 响应头,浏览器仍会强制 HTTPS。

**Google 维护的 preload list** 包含两类域名:

1. **站长主动提交的域名**:如 `github.com`、`paypal.com` 等,站长向 hstspreload.org 提交并满足条件(有效 HTTPS、所有子域名支持 HTTPS、max-age ≥ 18 周)。
2. **Google 自有的 TLD**:如 `.dev`、`.app`、`.foo`、`.page`、`.google` 等。这些 TLD 由 Google 注册,默认全部在 preload list 中,强制 HTTPS。

**关键行为**:

- `.dev` 域名在所有主流浏览器中被永久强制 HTTPS。
- 即使用户访问 `http://1dao.dev`,浏览器也会内部跳转为 `https://1dao.dev`。
- 如果该域名没有 HTTPS 服务,连接失败,无法用任何方式绕过。
- **退出 preload list 极其困难**:需要站长主动提交移除申请,Google 审核期可能长达数月,且需等到下次浏览器版本发布后,才会从 list 中移除。

这就是为什么本项目要避免使用 `.dev` 作为测试域名:`dev.1dao.cc`(eTLD 是 `.cc`)不会触发 `.dev` 的 HSTS,可以自由使用 HTTP。

### 2.3 eTLD+1(Effective Top-Level Domain plus one)

eTLD+1 是 Cookie 和 HSTS 策略计算的基础概念,定义如下:

- **eTLD(Effective Top-Level Domain)**:由 [publicsuffix list](https://publicsuffix.org/) 定义的有效顶级域名。例如 `.com`、`.org`、`.cc`、`.dev` 都是 eTLD。
- **eTLD+1**:eTLD 加上一级,通常是"可注册的域名"。例如 `1dao.cc` 是 `.cc` 的 eTLD+1,`1dao.dev` 是 `.dev` 的 eTLD+1。

**特殊情形**:有些"看起来像 TLD"的实际上是 eTLD+1。例如:

- `1dao.cc` → eTLD 是 `.cc`,eTLD+1 是 `1dao.cc`
- `1dao.dev` → eTLD 是 `.dev`,eTLD+1 是 `1dao.dev`
- `dev.1dao.cc` → eTLD 是 `.cc`,eTLD+1 是 `1dao.cc`(因为 `dev.1dao.cc` 是 `1dao.cc` 的子域名)

**HSTS includeSubDomains 的边界**:HSTS 头中的 `includeSubDomains` 只会扩展到与设置域名的 **eTLD+1 相同** 的子域名。例如对 `1dao.cc` 设置 `includeSubDomains`,扩展到 `dev.1dao.cc`、`admin.1dao.cc`,但**不会**扩展到 `1dao.cc` 之外的其他 eTLD+1(如 `1dao.dev`)。

### 2.4 为什么 dev.1dao.cc 不触发 .dev 的 HSTS

这是本项目中一个核心的设计决策点。许多人会问:"既然 `.dev` 在 preload list 中,那 `dev.1dao.cc` 这个域名中包含 `.dev`,会不会被强制 HTTPS?"

答案是**不会**。原因:

1. **eTLD 计算规则**:publicsuffix list 中,`.dev` 是一个 eTLD(顶级域),而 `.cc` 是另一个 eTLD。
2. **域名解析结构**:`dev.1dao.cc` 的层次是 `cc` → `1dao` → `dev`,eTLD 是 `cc`,eTLD+1 是 `1dao.cc`,`dev` 是 `1dao.cc` 的子域名。
3. **HSTS 触发条件**:浏览器判断一个域名是否在 preload list 时,是按"完整 eTLD+1"匹配的。`dev.1dao.cc` 的 eTLD+1 是 `1dao.cc`,不在 preload list 中;preload list 中的 `dev` 是作为 eTLD 存在的,影响的是 `xxx.dev` 这类域名(其 eTLD+1 形如 `1dao.dev`),而不是子串 `dev` 出现在其他域名中。

**对比表**:

| 域名 | eTLD | eTLD+1 | 是否受 .dev preload 影响 |
|------|------|--------|------------------------|
| `dev.1dao.cc` | `.cc` | `1dao.cc` | 否 |
| `1dao.dev` | `.dev` | `1dao.dev` | 是,强制 HTTPS |
| `admin.1dao.dev` | `.dev` | `1dao.dev` | 是,通过 includeSubDomains |
| `1dao.cc` | `.cc` | `1dao.cc` | 否 |

所以本项目中使用 `dev.1dao.cc` 作为测试域名是安全的,可以使用 HTTP;而如果改用 `1dao.dev` 作为测试域名,就必须提供有效 HTTPS 证书。

**eTLD+1 在 Cookie 域设置中的作用**:publicsuffix list 的存在意义之一,是防止"恶意 Cookie 注入"。考虑场景:某个公网站点 `evil.com` 试图设置 Domain 为 `.com` 的 Cookie。如果浏览器允许,这个 Cookie 会被发送到所有 `.com` 域名(包括 `bank.com`、`google.com` 等),造成严重的隐私泄露和身份伪造风险。publicsuffix 限制了"可注册的 eTLD+1 边界",让 Cookie 只能在同一个 eTLD+1 内共享,跨 eTLD+1 不可传播。

同理,HSTS 的 includeSubDomains 也受 eTLD+1 边界限制:对 `1dao.cc` 设置 includeSubDomains,只影响 `1dao.cc` 自己的子域名(`dev.1dao.cc`、`admin.1dao.cc`),不会影响 `2dao.cc` 或其他 eTLD+1。这保证了 HSTS 策略的隔离性,防止恶意站点通过设置 HSTS 影响其他站点的访问。

### 2.5 TLS 握手与 SNI

TLS 握手是 HTTPS 建立加密通道的过程。简化流程:

客户端 服务器

--- ClientHello -------------->	(含 SNI:期望访问的域名)
<-- ServerHello ----------------	(选定 TLS 版本、密码套件)
<-- Certificate ----------------	(服务器据此域名选证书返回)
<-- ServerHelloDone ------------
--- ClientKeyExchange --------->
--- ChangeCipherSpec ---------->
--- Finished ------------------>
<-- ChangeCipherSpec -----------
<-- Finished -------------------
=== 加密应用数据传输 =========

**SNI(Server Name Indication)**:在 ClientHello 阶段,客户端通过 TLS 扩展字段 `server_name` 明文告知服务器"我想访问哪个域名"。服务器收到后,从配置的多个证书中,选择与该域名匹配的证书返回。

SNI 的必要性:同一台服务器(同一 IP)的 443 端口可能服务多个域名(如 `1dao.cc` 和 `dev.1dao.cc`),每个域名有自己的证书。如果没有 SNI,服务器无法在 TLS 握手前知道客户端想访问哪个域名,只能返回默认证书,导致浏览器报证书不匹配错误。

**SNI 不匹配时的行为**:

- 服务器返回 `default_server` 配置的证书(nginx 概念)。
- 如果该证书的 SAN 中不包含客户端访问的域名,浏览器报"证书不受信任"。
- 如果 `default_server` 返回 nginx 的 444 状态码(详见 2.7),连接会被直接关闭。

诊断 SNI 的命令:

第三章:Cookie 与浏览器存储深度解析

3.1 Cookie 机制

Cookie 是 HTTP 协议中客户端保存少量状态数据的机制。服务器通过 Set-Cookie 响应头下发,浏览器在后续请求中通过 Cookie 请求头回传。

Set-Cookie 头的属性:

Set-Cookie: sessionid=abc123; Domain=.1dao.cc; Path=/; Max-Age=86400; Secure; HttpOnly; SameSite=Lax

属性	作用	默认行为
`Domain`	Cookie 所属域名	默认为响应服务器域名,不带前导点
`Path`	生效路径	默认为响应的 URL 路径
`Expires`	过期时间(绝对时间)	不设则为 Session Cookie,关闭浏览器即失效
`Max-Age`	过期时间(相对秒数)	优先级高于 Expires
`Secure`	仅 HTTPS 传输	不设则 HTTP 也会发送
`HttpOnly`	JS 不可访问	防止 XSS 读取 Cookie
`SameSite`	跨站发送策略	现代浏览器默认 Lax

Domain 属性的关键行为:

• 不写 Domain:Cookie 只属于当前精确域名。dev.1dao.cc 设置的 Cookie,不会发送到 1dao.cc 或 admin.1dao.cc。
• 写 Domain=.1dao.cc(注意前导点,现代浏览器忽略前导点,但语义是"覆盖所有 1dao.cc 的子域名和 1dao.cc 本身"):Cookie 会发送到 1dao.cc、dev.1dao.cc、admin.1dao.cc 等所有 eTLD+1 一致的域名。

Cookie 不分端口:http://1dao.cc:8080 和 http://1dao.cc:80 共享同一份 Cookie。这是 Cookie 的设计——端口不参与 Cookie 的隔离。

HttpOnly 的意义:设置了 HttpOnly 的 Cookie,document.cookie 取不到,也修改不了。这能防止 XSS 攻击者通过 JS 偷取登录态。本项目登录 Cookie 必须设 HttpOnly。

SameSite 三种取值:

• Strict:跨站请求完全不发送 Cookie。例如从 google.com 点链接到 1dao.cc,1dao.cc 不会收到 Cookie,用户需要重新登录。这是最严格的策略,但用户体验差(从外站进入总是未登录状态)。
• Lax:跨站导航(顶层 GET)发送,其他跨站请求(子资源、POST)不发送。这是 Chrome 80+ 默认值。Lax 模式在安全性和易用性之间取得平衡,大多数普通链接跳转可携带登录态,但 POST 请求(典型如 CSRF 攻击)不会带上 Cookie,从根本上缓解了 CSRF 攻击。
• None:完全发送,但必须配合 Secure(即仅 HTTPS)。旧版本默认 None。在 Chrome 80 之后,如果不显式声明 SameSite=None,会被当作 Lax 处理,这给许多旧系统带来兼容性问题——特别是依赖跨站 Cookie 的第三方嵌入式应用(如支付回调、SSO 跳转)。

SameSite 在跨站判定上的逻辑:浏览器判断"是否跨站",看的是顶级域名是否变化。dev.1dao.cc 跳转到 1dao.cc 算"同站"(eTLD+1 都是 1dao.cc),Cookie 会发送;而 dev.1dao.cc 跳转到 crmeb.example.com 算"跨站",在 Strict 模式下不发送 Cookie。这也提醒我们:Cookie 的同站判定基于 eTLD+1,而 localStorage 的同源判定基于完整 origin,两者不是一回事。

3.2 同域名 Cookie 共享问题

本项目最初的错误设计是 dev 和线上环境共用域名 1dao.cc(仅通过不同路径区分),导致了严重的 Cookie 串扰:

访问 dev.1dao.cc → 写入 Cookie: domain=.1dao.cc, name=login_token, value=dev_xxx
访问 1dao.cc     → 浏览器自动附带 login_token=dev_xxx
                 → 服务器以为是 dev 环境的登录态
                 → 线上环境收到 dev 的 Cookie,数据混乱

解决方案:

1. 使用不同子域名:dev 用 dev.1dao.cc,线上用 1dao.cc,admin 用 admin.1dao.cc。Cookie 设 Domain 时只用精确域名,不用 .1dao.cc:

   setcookie('login_token', $token, [
       'domain' => 'dev.1dao.cc',  // 注意:不带前导点
       'secure' => true,
       'httponly' => true,
       'samesite' => 'Lax',
   ]);

1. 使用不同浏览器:开发用 Chrome,线上用 Firefox,各自独立的 Cookie 存储。这是临时方案,治标不治本。
2. 使用不同浏览器 Profile:Chrome 支持多 Profile,各 Profile 独立 Cookie。比"不同浏览器"更优雅。

最终本项目采用方案 1,通过 dev.1dao.cc / 1dao.cc 子域名隔离,彻底消除 Cookie 串扰。

3.3 localStorage

localStorage 是 HTML5 引入的客户端持久化存储,5-10MB 容量,按 origin 隔离:

• origin = scheme + host + port
• http://1dao.cc 和 https://1dao.cc 是不同 origin,localStorage 不共享
• http://1dao.cc:80 和 http://1dao.cc:8080 是不同 origin,localStorage 不共享
• http://1dao.cc 和 http://dev.1dao.cc 是不同 origin,localStorage 不共享

关键差异(对比 Cookie):Cookie 按"domain"匹配,不分端口;localStorage 按"origin"隔离,分端口。这意味着:

• 如果 dev 和线上环境共用域名(仅不同端口),Cookie 会串扰,但 localStorage 不会。
• 如果 dev 和线上环境共用域名同端口(仅不同路径),Cookie 和 localStorage 都会串扰。

localStorage API:

localStorage.setItem('user', JSON.stringify({id: 1, name: 'admin'}));
const user = JSON.parse(localStorage.getItem('user'));
localStorage.removeItem('user');
localStorage.clear();  // 清空所有

localStorage 不能跨 origin 访问,即使是父域名的 JS 也无法读取子域名的 localStorage,反之亦然。这是与 Cookie 的关键区别:Cookie 可以"父域名写,子域名读",localStorage 严格按 origin 隔离。

3.4 Service Worker

Service Worker(SW)是浏览器在页面之外运行的 JavaScript 工作线程,可拦截其注册 origin 下的所有请求。典型用途:PWA 离线缓存、推送通知、后台同步。

关键陷阱:SW 一旦注册,会持续存在,即使关闭浏览器、重启电脑,只要在 SW 的有效期(默认 24 小时检查更新)和存储清理前未被注销,就会继续拦截请求。

测试环境中的具体问题:

1. 开发者在 dev 环境注册了 SW(用于测试 PWA)
2. SW 缓存了 dev 环境的 index.html
3. 开发者切换到线上环境访问
4. SW 仍存在,拦截请求,返回 dev 的缓存页面
5. 表现:明明 hosts 已切到线上,但页面内容还是 dev 的

排查方法:

## 第四章:Shell 脚本技术原理

### 4.1 set 命令详解

`set` 命令用于修改 shell 的运行时选项。最常用的三个是:

set -e # errexit:命令失败立即退出

set -u # nounset:未定义变量报错

set -o pipefail # 管道中任一环节失败即报错

**`set -u` 的实际作用**:任何对未定义变量的引用都会触发错误并退出脚本。这是防止"幽灵变量"导致逻辑错误的重要保障。例如:

#!/bin/bash

set -u

echo "Hello, $NAME!" # 如果 NAME 未定义,直接报错退出

如果不加 `set -u`,脚本会继续执行,把 `$NAME` 当作空字符串,导致输出"Hello, !",看似无害,但在生产场景中可能引发数据写入错误(例如把空值写入数据库)。`set -u` 的代价是脚本中需要确保所有变量都已定义,有时需要预先赋默认值:`NAME=${NAME:-default}`。

**`set -e` 的"陷阱清单"**:

1. **命令在 `if`/`while`/`&&`/`||` 条件中失败,不触发退出**。这是 bash 的设计——条件判断的失败是"预期行为",不视为错误。
2. **管道中除最后一条命令失败,默认不触发退出**。需要 `pipefail` 才能让中间命令的失败也生效。
3. **函数内部失败,默认会传播到调用点**。但如果函数被用在 `if` 中,失败同样被忽略。
4. **子 shell 中的失败不传播**。`(false; echo "still alive")` 会打印 "still alive"。
5. **`! cmd` 反转退出码后,失败也不触发退出**。这是逻辑取反的副作用。

这些特性使得 `set -e` 的实际行为经常与直觉相悖。因此,在生产脚本中,关键操作往往手动检查退出码,而不是完全依赖 `set -e`:

if ! mysql -uroot 1dao_db -e "REPLACE INTO ..."; then

echo "ERROR: 替换失败" >&2

exit 1

fi

组合使用 `set -euo pipefail` 是 shell 脚本的"最佳实践",但在循环和管道场景中有陷阱:

**陷阱示例**:本项目早期版本中,switch-env 脚本循环处理多张表:

#!/bin/bash

set -euo pipefail

while IFS=$'\t' read -r table col; do

mysql -uroot 1dao_db -e "REPLACE INTO $table ($col) VALUES ('dev_value')"

done < <(mysql -uroot 1dao_db -sN -e "SELECT table_name, column_name FROM ...")

如果某张表暂时不存在(例如某次循环中 mysql 报错),`set -e` 会让整个脚本立即退出,**剩余的表不会被处理**,但前面的表已经修改,导致数据库处于"半切换"状态。

**替代方案**:在循环中临时关闭 errexit:

while IFS=$'\t' read -r table col; do

set +e

mysql -uroot 1dao_db -e "REPLACE INTO $table ($col) VALUES ('dev_value')"

set -e

done < <(...)

或更简洁,使用 `|| true`:

while IFS=$'\t' read -r table col; do

mysql -uroot 1dao_db -e "REPLACE INTO ... " || true

done < <(...)

`|| true` 的语义是:无论 mysql 成功还是失败,该复合命令的退出码都是 0,因此不会触发 `set -e`。

**pipefail 的陷阱**:

mysql -uroot 1dao_db -e "SELECT ..." | grep "something"

如果 mysql 失败但 grep 成功(因为 grep 找到了匹配),那么 `pipefail` 让整个管道的退出码反映 mysql 的失败,触发 `set -e`。如果这是在循环中,会终止整个循环。

### 4.2 shell 数组与排序

bash 的数组语法:

第五章:数据库快照原理

5.1 mysqldump 机制

mysqldump 是 MySQL 自带的逻辑备份工具,通过执行 SQL 语句重建数据库。它与 mysqlbinlog(基于 binlog 的物理备份)、Percona XtraBackup(物理热备份)相比,优势在于通用性强、跨版本兼容性好;劣势是备份和恢复较慢,因为需要执行大量 SQL 语句重建数据。

逻辑备份 vs 物理备份对比:

维度	逻辑备份(mysqldump)	物理备份(XtraBackup)
实现方式	执行 SELECT 拿数据 + 生成 SQL	直接拷贝数据文件
速度	慢(受 SQL 解析开销)	快(直接 IO)
恢复速度	慢(逐条执行 SQL)	快(直接拷贝)
跨版本兼容	好	差(文件格式可能不兼容)
锁表影响	InnoDB 用一致性读不锁表	几乎无锁
备份文件大小	较大(纯文本 SQL)	较小(二进制)
单表恢复	支持(从备份文件提取)	不支持(整体恢复)

关键参数:

mysqldump -uroot \
  --single-transaction \
  --databases 1dao_db \
  --routines \
  --triggers \
  --default-character-set=utf8mb4 \
  | gzip > /var/lib/1dao-env/prod.sql.gz

各参数含义:

• --single-transaction:使用 InnoDB 的 MVCC 机制,在一致性读视图中导出。不锁表,但要求所有表是 InnoDB,且导出期间不能执行 DDL(ALTER/ DROP 等)。
• --databases:导出内容包含 CREATE DATABASE 和 USE 语句。恢复时 mysql < dump.sql 即可自动创建库。如果不加此参数,导出不含建库语句,需手动 CREATE DATABASE。
• --routines:导出存储过程和函数。
• --triggers:导出触发器(默认开启,显式声明便于阅读)。
• --default-character-set=utf8mb4:确保 UTF-8 4 字节字符(如表情符号)正确导出。

管道的应用:

## 第六章:nginx 配置原理

### 6.1 server_name 匹配优先级

nginx 收到 HTTP 请求后,按以下顺序匹配 `server` 块:

1. **精确匹配**:`server_name 1dao.cc;` 严格等于 Host 头。
2. **通配符开头**:`server_name *.1dao.cc;` 匹配 `dev.1dao.cc`、`admin.1dao.cc` 等。
3. **通配符结尾**:`server_name 1dao.*;` 匹配 `1dao.com`、`1dao.net` 等。
4. **正则匹配**:`server_name ~^dev\d+\.1dao\.cc$;` 匹配 `dev1.1dao.cc`、`dev2.1dao.cc` 等。正则需以 `~` 开头。
5. **default_server**:`listen 80 default_server;` 标记的服务器,处理所有未匹配的请求。

**示例**:

第七章:故障排查手册

7.1 "您的连接不是私密连接" 排查流程

浏览器报"您的连接不是私密连接"(NET::ERR_CERT_AUTHORITY_INVALID 等),意味着 TLS 证书校验失败。

常见的错误代码及其含义:

错误代码	含义	常见原因
`NET::ERR_CERT_AUTHORITY_INVALID`	证书颁发机构不受信任	自签名证书未导入信任
`NET::ERR_CERT_COMMON_NAME_INVALID`	证书 CN/SAN 不匹配	访问的域名不在证书 SAN 中
`NET::ERR_CERT_DATE_INVALID`	证书过期或未生效	系统时间错误,或证书到期
`NET::ERR_CERT_AUTHORITY_INVALID`	证书链不完整	中间证书未配置
`NET::ERR_SSL_PROTOCOL_ERROR`	SSL 握手失败	TLS 版本不匹配,或 SNI 配置错误

排查步骤:

1. 检查 URL 是 HTTP 还是 HTTPS

- 如果地址栏显示 http:// 但页面错误,检查是否被 HSTS 强制改写。

- 在 chrome://net-internals/#hsts 查询该域名是否在 HSTS 缓存中。

1. 检查证书是否匹配域名

   openssl s_client -connect 192.168.207.130:443 -servername dev.1dao.cc < /dev/null 2>/dev/null \
     | openssl x509 -noout -subject -ext subjectAltName

输出示例:

   subject=CN = 1dao.cc
   X509v3 Subject Alternative Name:
       DNS:1dao.cc, DNS:*.1dao.cc

- 如果访问的 dev.1dao.cc 不在 SAN 中,浏览器报错。

- 如果是自签名证书,需要手动添加到系统钥匙串信任。

1. 检查是否在 HSTS preload list

- 访问 hstspreload.org 查询域名。

- 如果用了 .dev / .app 等 Google TLD,会被强制 HTTPS。即使提供 HTTP,浏览器仍会改写为 HTTPS。

1. 检查浏览器 HSTS 缓存

- chrome://net-internals/#hsts

- 在 "Query HSTS/PKP domain" 输入域名,查询是否被缓存。

- 在 "Delete domain security policies for domain" 删除该域名。

1. 检查系统时间

- 证书有效期是绝对时间。如果系统时间不对(如 1970 年或 2030 年),所有证书都会被认为过期。

- date 命令检查时间是否正确。

完整流程图:

"您的连接不是私密连接"
        |
        v
是 HTTP 还是 HTTPS?
   |              |
HTTP            HTTPS
   |              |
   v              v
检查是否被 HSTS   检查证书 SAN 是否匹配
强制改写为 HTTPS   |
   |              v
   v              证书匹配?
在 HSTS 缓存?     |        |
   |           是        否
   v            |        |
是            v        v
删除 HSTS     完成    证书是否自签名?
缓存                  |        |
   |                是        否
   v                |        |
重新访问          v        v
                 添加信任  检查证书
                 到钥匙串  链是否完整

7.2 "站点无法访问" 排查流程

浏览器报"站点无法访问"(ERR_CONNECTION_REFUSED、ERR_CONNECTION_TIMED_OUT 等)。

排查步骤:

1. ping 域名,检查 DNS 解析

   ping dev.1dao.cc
   # 如果 ping 不通域名,但 ping IP 通,是 DNS 问题
   # 如果 ping IP 也不通,是网络层问题

1. curl -v 检查连接

   curl -v http://dev.1dao.cc/
   # 输出:
   # *   Trying 192.168.207.130:80...
   # * connect to 192.168.207.130 port 80 failed: Connection refused

- Connection refused:虚机在线但 80 端口未监听(nginx 未启动)。

- Connection timed out:虚机不在线或防火墙拦截。

- Trying 1.2.3.4(非虚机 IP):DNS 解析错误,检查 hosts。

1. ssh 虚机,检查服务状态

   ssh vagrant@192.168.207.130
   sudo systemctl status nginx
   sudo systemctl status php8.1-fpm

1. 检查 nginx error.log

   sudo tail -50 /var/log/nginx/error.log
   # 看是否有 "host not found in upstream"(后端域名解析失败)
   # 或 "permission denied"(文件权限)
   # 或 "no live upstreams"(后端全挂)

1. 检查虚机防火墙

   sudo ufw status
   # 如果 80/443 未开放:
   sudo ufw allow 80
   sudo ufw allow 443

1. 检查 macOS hosts 文件

   grep 1dao.cc /etc/hosts
   # 应输出:192.168.207.130 1dao.cc dev.1dao.cc ...

7.3 "页面空白/500" 排查流程

页面打开但空白,或返回 500(Internal Server Error)。

排查步骤:

1. curl -I 检查状态码

   curl -I http://dev.1dao.cc/
   # HTTP/1.1 500 Internal Server Error
   # HTTP/1.1 200 OK 但内容空白

1. 查 nginx error.log

   sudo tail -50 /var/log/nginx/error.log
   # PHP message: PHP Fatal error:  Uncaught ...
   # 或:FastCGI sent in stderr: "Primary script unknown"

1. 查 PHP-FPM 错误日志

   sudo tail -50 /var/log/php8.1-fpm.log

1. 查应用日志

   sudo tail -50 /var/www/1dao/storage/logs/laravel.log
   # 或 crmeb:
   sudo tail -50 /var/www/crmeb/runtime/log/$(date +%Y%m)/$(date +%d).log

1. 检查文件权限

   ls -la /var/www/1dao/storage/
   # storage/ 和 bootstrap/cache/ 必须 www-data 可写
   sudo chown -R www-data:www-data /var/www/1dao/storage
   sudo chown -R www-data:www-data /var/www/1dao/bootstrap/cache

1. 检查数据库连接

   # 在虚机上测试 mysql 连接
   mysql -u1dao -p$(grep DB_PASSWORD /var/www/1dao/.env | cut -d= -f2) 1dao_db -e "SELECT 1"
   # 如果连接失败:检查 .env 中 DB_HOST/DB_PORT/DB_PASSWORD

1. 清缓存

   # Laravel
   cd /var/www/1dao
   php artisan cache:clear
   php artisan config:clear
   php artisan route:clear
   php artisan view:clear

   # Redis 缓存
   redis-cli FLUSHALL

   # crmeb runtime
   rm -rf /var/www/crmeb/runtime/cache/*
   rm -rf /var/www/crmeb/runtime/temp/*

7.4 "切换 hosts 后浏览器仍访问旧环境" 排查

明明 which-env 显示当前是 dev 模式,但浏览器仍访问线上环境。

排查步骤:

1. which-env 确认系统层面

   which-env
   # 应输出: Current environment: dev (pointing to 192.168.207.130)
   # 同时 ping 1dao.cc 应解析到 192.168.207.130
   ping -c 1 1dao.cc

1. 清浏览器 DNS 缓存

- Chrome:chrome://net-internals/#dns → "Clear host resolver cache"

- Firefox:about:networking#dns → "Clear DNS Cache"

1. 清 Socket 连接池

- 浏览器会复用已建立的 TCP 连接(keepalive)。如果旧连接还在,即使 DNS 已切换,仍走旧 IP。

- Chrome:chrome://net-internals/#sockets → "Flush socket pools"

- 或关闭所有浏览器窗口重开。

1. 用无痕窗口验证

- 无痕窗口有独立的 DNS 缓存和 socket 池。

- 如果无痕窗口正常而普通窗口异常,确认是浏览器缓存问题。

1. 检查 Service Worker

- SW 拦截请求可能返回旧环境的缓存。

- chrome://serviceworker-internals/ 注销所有 SW。

1. 检查 HSTS 缓存

- 如果之前访问过 https://1dao.cc,可能被 HSTS 强制 HTTPS,导致访问 dev 也走 HTTPS,但 dev 环境只有 HTTP,连接失败或回退到线上。

- chrome://net-internals/#hsts 删除 1dao.cc 的 HSTS 策略。

7.5 "switch-env 切换后数据没变" 排查

执行了 switch-env dev,但访问页面发现域名、数据仍是 prod 状态。

排查步骤:

1. 检查 env.conf 的 CURRENT

   cat /var/lib/1dao-env/env.conf
   # 应输出: CURRENT=dev
   # 如果仍是 CURRENT=prod,说明脚本未执行到最后一步

1. 检查快照是否存在

   ls -la /var/lib/1dao-env/
   # dev.sql.gz 应存在,且修改时间是最近
   # 如果 dev.sql.gz 不存在或时间过早,restore 失败但未报错

1. 检查数据库实际值

   mysql -uroot 1dao_db -e "SELECT value FROM tb_config WHERE name='site_url'"
   # 应输出 dev.1dao.cc
   # 如果仍是 1dao.cc,数据库未切换成功

1. 检查 set -euo pipefail 是否导致脚本提前退出

   # 临时修改脚本,在每步后加 echo 调试
   bash -x /usr/local/bin/switch-env dev
   # -x 选项打印每条命令,查看哪一步退出

1. 检查 CONCAT 的 \t 问题

   # 如果脚本中有:
   # mysql -e "SELECT CONCAT(a, '\t', b) FROM ..."
   # 实际输出不是 a<TAB>b,而是 a\tb
   # read 命令拿不到正确的两个字段
   # 改为 SELECT a, b 解决

1. 检查 nginx 配置是否 reload

   sudo nginx -t
   sudo systemctl reload nginx
   # nginx 配置改了但不 reload,旧配置仍生效

1. 检查 .env 文件

   grep -E 'APP_URL|DOMAIN' /var/www/1dao/.env
   # 应为 dev.1dao.cc

7.6 "WiFi 断开时域名无法访问" 排查

关闭 WiFi 后,即使 hosts 配置正确,虚机在线,仍无法访问 dev.1dao.cc。

排查步骤:

1. 确认虚机 IP 可达

   ping 192.168.207.130
   # 应能 ping 通(虚机在线)

1. 用 IP+端口直连绕过 DNS

   curl -H "Host: dev.1dao.cc" http://192.168.207.130/
   # 如果能返回页面,说明 nginx 和 PHP 都正常
   # 问题在 DNS 解析层

1. 确认 hosts 条目存在

   grep 1dao /etc/hosts
   # 应输出:192.168.207.130  1dao.cc dev.1dao.cc ...

1. 理解 macOS 无网络时不解析 hosts

- 这是 macOS 的已知行为。WiFi 断开时,mDNSResponder 没有活动网络接口,即使 hosts 文件有配置也不解析。

- 验证:ping 1dao.cc 会报 Unknown host,但 ping 192.168.207.130 正常。

1. 解决方案

- 重新连接 WiFi(哪怕 WiFi 不通外网,只要接口 active 即可)。

- 创建虚拟网络接口:

     sudo ifconfig lo0 alias 127.0.0.2 up
     # 这会让系统认为有活动接口,mDNSResponder 开始工作

- 用 IP+Host 头直连,绕过 DNS。

---

第八章:完整命令速查手册

8.1 macOS 主机命令

## 第九章:项目完整时间线

以下是本次开发测试环境搭建的关键操作时间线,按顺序记录每个决策点和遇到的坑。

### 阶段一:环境规划(上午 09:00-10:00)

- 09:00 评估需求:dev 环境与 prod 环境共用数据库,导致数据串扰严重,需物理隔离。
- 09:15 决定方案:用 VirtualBox + Vagrant 搭建独立虚机,在虚机上运行 dev 环境。
- 09:30 选定虚机配置:Ubuntu 22.04 LTS、2GB 内存、2 CPU、IP 192.168.207.130。
- 09:45 决定域名策略:dev 环境用 `dev.1dao.cc` 子域名,避免与 `1dao.cc` 共用 Cookie。

### 阶段二:虚机初始化(上午 10:00-11:00)

- 10:00 `vagrant init ubuntu/jammy64` 创建 Vagrantfile。
- 10:15 配置 Vagrantfile:私有网络 IP、 forwarded_port、synced_folder。
- 10:30 `vagrant up` 启动虚机,遇到 VirtualBox 内核模块加载失败。
  - 排查:`kextstat | grep -v com.apple` 查看扩展加载情况。
  - 解决:macOS 系统设置允许 Oracle 加载扩展。
- 10:45 `vagrant ssh` 进入虚机,基础环境就绪。

### 阶段三:服务安装(上午 11:00-下午 13:00)

- 11:00 安装 nginx:`apt install nginx`。
- 11:15 安装 PHP-FPM 8.1 + 常用扩展:`apt install php8.1-fpm php8.1-mysql php8.1-redis php8.1-gd php8.1-mbstring`。
- 11:30 安装 MySQL 8.0:`apt install mysql-server`,运行 `mysql_secure_installation`。
- 11:45 安装 Redis:`apt install redis-server`。
- 12:00 配置 PHP-FPM:修改 `www.conf`,调整 `pm.max_children = 30`。
- 12:15 配置 MySQL:修改 `mysqld.cnf`,设置 `character-set-server = utf8mb4`。
- 12:30 测试各服务:`systemctl status nginx/php8.1-fpm/mysql/redis`。

### 阶段四:应用部署(下午 13:00-15:00)

- 13:00 拉取代码:`git clone` 到 `/var/www/1dao`。
- 13:15 `composer install` 安装 PHP 依赖。
- 13:30 配置 .env 文件:数据库连接、Redis 连接、APP_URL 设为 `http://dev.1dao.cc`。
- 13:45 `php artisan key:generate` 生成应用密钥。
- 14:00 `php artisan migrate` 执行数据库迁移。
- 14:15 `php artisan db:seed` 填充测试数据。
- 14:30 导入 prod 数据库快照:`gunzip -c prod.sql.gz | mysql 1dao_db`。
- 14:45 测试访问 `curl http://localhost/`,确认应用可访问。

### 阶段五:nginx 配置(下午 15:00-16:00)

- 15:00 创建 `/etc/nginx/conf.d/1dao.conf`:配置 server_name `dev.1dao.cc`、root 指向 `/var/www/1dao/public`、try_files 重写、fastcgi_pass 到 PHP-FPM socket。
- 15:15 创建 `/etc/nginx/conf.d/000-default-444.conf`:default_server + return 444,拦截未配置的请求。
- 15:30 `nginx -t` 测试配置通过,`systemctl reload nginx`。
- 15:45 配置 X-Environment 头:`add_header X-Environment "dev" always;`。
- 16:00 在 macOS hosts 中写入 `192.168.207.130 dev.1dao.cc`,测试访问成功。

### 阶段六:DNS 与 HTTPS(下午 16:00-17:00)

- 16:00 尝试访问 `https://dev.1dao.cc`,报"您的连接不是私密连接"。
  - 排查:浏览器 HSTS 缓存了 1dao.cc 的 HTTPS 策略。
  - 解决:`chrome://net-internals/#hsts` 删除 1dao.cc 的 HSTS 缓存。
- 16:15 测试 `http://1dao.dev`(误用),报错强制 HTTPS。
  - 排查:`.dev` 在 HSTS preload list,无法用 HTTP。
  - 解决:改用 `dev.1dao.cc`(eTLD 是 `.cc`,不受 `.dev` 影响)。
- 16:30 生成自签名证书:`openssl req -x509 -newkey rsa:2048 -nodes ... -config openssl.cnf`。
- 16:45 配置 HTTPS server,但测试发现不需要 HTTPS 也能用,最终决定 dev 用 HTTP。

### 阶段七:Cookie 串扰(下午 17:00-18:00)

- 17:00 切换 dev-on 后,访问 `1dao.cc` 发现登录态是 dev 的。
- 17:15 排查:Cookie 的 Domain 设为 `.1dao.cc`,导致 dev 和 prod 共享 Cookie。
- 17:30 修改 PHP 代码:setcookie 的 domain 改为精确域名 `dev.1dao.cc`。
- 17:45 测试:dev 和 prod 的 Cookie 隔离,登录态独立。

### 阶段八:Shell 脚本(下午 18:00-19:00)

- 18:00 编写 `dev-on`、`dev-off`、`which-env` 脚本。
- 18:15 编写 `switch-env`、`change-domain` 脚本。
- 18:30 测试 switch-env,发现数据库没切换。
  - 排查:`set -euo pipefail` 导致循环中 mysql 失败即终止。
  - 解决:循环中加 `|| true`。
- 18:45 测试 change-domain,发现输出格式错误。
  - 排查:`CONCAT(table, '\t', col)` 输出的不是制表符。
  - 解决:改用 `SELECT table, col`(mysql -sN 自动用 tab 分隔)。
- 19:00 所有脚本测试通过。

### 阶段九:故障排查(下午 19:00-20:00)

- 19:00 浏览器仍访问旧环境。
  - 排查:Chrome DNS 缓存未清。
  - 解决:`chrome://net-internals/#dns` 清缓存。
- 19:15 WiFi 断开后无法访问 dev 域名。
  - 排查:macOS 无活动接口时,mDNSResponder 不解析 hosts。
  - 解决:重新连接 WiFi。
- 19:30 Service Worker 拦截请求。
  - 排查:`chrome://serviceworker-internals/` 看到 dev 注册的 SW。
  - 解决:Unregister 所有 SW。
- 19:45 完整流程跑通,提交代码。

### 阶段十:文档编写(晚上 20:00-22:00)

- 编写本系列工作总结文档,共六部分。
- 本部分(第六部分)聚焦技术原理与故障排查。

---

## 第十章:总结与展望

### 10.1 完成的工作总结

本次开发测试环境搭建工作,完成了以下核心成果。整个工作从最初的"数据串扰问题"识别,到最终的"完整工具链交付",历时约一整个工作日,过程中既验证了已有的网络、DNS、TLS、浏览器存储等知识,也通过踩坑补齐了 Shell 脚本陷阱、SQL 转义、macOS 特殊行为等实战盲区。

**架构层面**:
- 在 macOS 主机上搭建独立的 VirtualBox 虚机作为 dev 环境,与线上 prod 环境物理隔离。
- 通过子域名(`dev.1dao.cc`、`admin.1dao.cc`、`api.1dao.cc`)实现 dev/prod 的 Cookie 隔离。
- 通过 nginx 的 default_server + return 444 拦截寄生域名和未配置请求。

**工具链层面**:
- 在 macOS 主机上提供 `dev-on`、`dev-off`、`which-env` 三个命令,一键切换开发态/线上态。
- 在虚机上提供 `switch-env`、`change-domain` 命令,支持数据库快照切换和域名批量替换。
- 建立了完整的环境标识体系(env.conf、X-Environment 头、应用 .env 文件)。

**数据层面**:
- 实现了 dev 和 prod 模式的双快照备份/恢复,数据相互隔离。
- 在切换环境时保留业务数据,确保开发进度不丢失。
- 通过 mysqldump --single-transaction 实现一致性快照,避免锁表。

**文档层面**:
- 本系列工作总结六部分,覆盖背景、架构、脚本、nginx、数据库、原理排错。
- 提供完整的命令速查手册和故障排查流程。
- 记录项目时间线和决策点,便于后续工程师理解。

**遇到并解决的关键问题**:
1. **HSTS 误用 .dev 域名**:认识到 `.dev` 在 preload list,改用 `dev.1dao.cc`。
2. **Cookie 跨子域共享**:理解 eTLD+1 和 Cookie Domain 的关系,改用精确域名。
3. **macOS DNS 缓存**:理解 mDNSResponder 的工作机制,正确刷新缓存。
4. **Shell 脚本陷阱**:理解 `set -euo pipefail` 在循环中的副作用,用 `|| true` 规避。
5. **SQL 转义陷阱**:理解 MySQL 字符串中 `\t` 不是制表符,改用 `SELECT col1, col2`。
6. **浏览器多级缓存**:理解 Memory/Disk/SW/HSTS 四层缓存,逐一清理。
7. **WiFi 断开不解析 hosts**:理解 macOS 无网络时的特殊行为,提供绕过方案。

### 10.2 待解决的问题

1. **walle / deploy 的 secrets 包**:目前 walle 部署系统中存在 secrets 包管理问题,部署时部分敏感配置(数据库密码、API key)的注入流程不够顺畅。需要研究 walle 的 secrets 集成机制,或改用 Ansible Vault。

2. **证书续期**:目前使用自签名证书,浏览器报警告。需考虑:
   - 申请 Let's Encrypt 免费证书(但 dev 环境在内网,无法完成 HTTP-01 验证)。
   - 使用 mkcert 生成被本机信任的本地证书。
   - 把根证书安装到系统钥匙串,使所有由 mkcert 签发的证书都被信任。

3. **Service Worker 的清理自动化**:目前每次切换环境都要手动 `chrome://serviceworker-internals/` 注销 SW。需要研究是否能在应用层面,通过版本号变化触发 SW 自动注销。

4. **数据库快照的版本管理**:目前 dev.sql.gz 和 prod.sql.gz 是单文件覆盖式,无版本历史。需考虑:
   - 引入 git-lfs 或 git-annex 管理快照版本。
   - 或保留最近 N 个快照(`dev-20240101.sql.gz`、`dev-20240102.sql.gz`),定期清理。

5. **跨主机部署**:目前 dev 环境绑定在单台虚机上,如果多人协作开发,需要每人各自部署。后续考虑:
   - 用 Docker 容器化,通过 docker-compose 一键启动。
   - 或用 Vagrant 的多机配置,支持多人共享一台虚机。

### 10.3 未来改进方向

**短期(1-2 周)**:

1. **自动化部署脚本完善**:
   - 编写 `deploy.sh`,一键完成代码更新、依赖安装、缓存清理、服务重启。
   - 集成 `git pull`、`composer install`、`php artisan migrate`、`systemctl reload` 等步骤。
   - 加入回滚机制:部署失败时自动回滚到上一版本。
   - 部署前自动备份当前数据库,出错可手工恢复。备份命名规则:`1dao_db_$(date +%Y%m%d_%H%M%S).sql.gz`,定期清理超过 7 天的旧备份。

2. **CI/CD 流水线**:
   - 在 GitLab CI / Jenkins 中配置流水线,代码 push 触发自动测试 + 部署到 dev 环境。
   - 测试通过后人工审核,部署到 prod 环境。
   - 集成 PHP_CodeSniffer、PHPStan 等静态检查工具。

3. **监控告警**:
   - 在 dev 虚机上部署 Prometheus + Grafana,监控 CPU、内存、磁盘、网络。
   - 在 nginx 上启用 stub_status,监控请求量、响应时间。
   - 在 MySQL 上启用 performance_schema,监控慢查询、连接数。
   - 配置告警:磁盘 >80%、服务宕机、慢查询激增时邮件 / 飞书通知。

**中期(1-2 月)**:

1. **容器化改造**:
   - 将 1dao 应用、crmeb 应用、MySQL、Redis 各自容器化。
   - 用 docker-compose 编排,实现一键启停。
   - 通过 volume 挂载实现数据持久化。
   - 支持多套环境并行(dev、staging、test),各自独立容器组。

2. **日志集中化**:
   - 部署 ELK(Elasticsearch + Logstash + Kibana)或 Loki + Grafana。
   - 收集 nginx、PHP-FPM、MySQL、应用日志。
   - 支持按域名、按环境、按时间维度检索。

3. **域名管理的进一步自动化**:
   - 编写一个 watch 守护进程,监控 hosts 文件变化,自动触发 DNS 缓存刷新。
   - 或开发 macOS 系统扩展(System Extension),提供更稳定的 dev/prod 切换。

**长期(3-6 月)**:

1. **多环境支持**:
   - 支持 feature branch 模式:每个功能分支自动部署到独立子域名(`feature-xyz.1dao.cc`)。
   - 用 PR 合并后自动销毁对应环境,节省资源。

2. **测试自动化**:
   - 引入 PHPUnit + Laravel Dusk,编写单元测试和浏览器测试。
   - 部署后自动运行测试,失败则回滚。
   - 集成到 CI/CD 流水线,作为部署门禁。

3. **性能基线**:
   - 在 dev 环境运行 k6 或 JMeter 压测,建立性能基线。
   - 每次代码变更后跑一次,对比基线,发现性能回归。
   - 报告响应时间、QPS、错误率等指标。

4. **安全加固**:
   - 定期扫描依赖漏洞:`composer audit`、`npm audit`。
   - 配置 WAF(ModSecurity),拦截常见攻击(SQL 注入、XSS)。
   - 启用 nginx 的 limit_req,防 CC 攻击。
   - 数据库定期审计,删除无用的测试账号。

### 结语

本次开发测试环境搭建工作,虽然过程曲折(踩了 DNS、HSTS、Cookie、Shell 脚本、SQL 转义等多个坑),但最终交付了一套稳定可用、文档完善、可扩展的环境管理工具。过程中积累的底层知识(DNS 解析栈、TLS 握手、Cookie 隔离、浏览器缓存层级),对后续运维和排错都有长远价值。

本系列文档(六部分)既是工作总结,也是知识库。后续工程师遇到类似问题,可直接对照原理章节和故障排查手册,快速定位和解决问题。文档中的命令示例均经过实际验证,可直接复制执行;流程图和表格可用于团队培训和新成员上手;故障排查章节可作为值班排错的参考手册。

如读者发现文档中的疏漏或错误,欢迎指正。技术演进日新月异,本手册描述的命令行为、配置语法,基于 2026 年的 macOS Sonoma、Ubuntu 22.04、nginx 1.22、PHP 8.1、MySQL 8.0,后续版本可能有差异,使用时请对照官方文档。建议每次大版本升级后,对文档中受影响的章节做一次回测和修订,保持内容与实际环境同步。

---

*文档版本:v1.0*
*完成日期:2026-08-21*
*适用环境:macOS Sonoma + VirtualBox 7.0 + Ubuntu 22.04 + nginx 1.22 + PHP 8.1 + MySQL 8.0*