WIP: XZH-21 后端改动 + 测试验收附加用例

This commit is contained in:
AAT committed 2026-11-11 20:41:56 +08:00
commit 1bd637528d
168 files changed
+13874

No files matched your search

+86
View File
@@ -0,0 +1,86 @@
# Docker Compose 容器验收
2026-11-10 实测通过:前后端容器构建、数据库迁移、18 项创建阶段检查、10 项重建后检查,以及 Chromium 登录/工作台/笔记/文件/退出流程。三个容器 ID 均已变化,笔记版本和文件 SHA256 保持一致。测试记录已清理,服务保留运行在 http://localhost:8088 ,登录信息见本机 `.local/container-access.md`。
不连接本机开发数据库(127.0.0.1:55432),不使用本机资产目录。测试配置在 Git 忽略的 `.local/container-test.env`,权限为 600。
2026-11-10 晚 `compose.yml` 统一为单一栈:固定项目名 `name: myspace`,数据卷 `myspace_postgres-data` / `myspace_asset-data`;后端健康检查通过后才启动前端。此前按目录名运行的 `myspace_hifox` 栈已停止(容器移除,数据卷保留,未被新栈使用),旧的 `-p myspace-container-test` 命令不再适用。
## 可重复执行
从工程根目录运行。先填写测试环境文件(参考 `.env.example`),并确保 8088 和 5432 端口空闲。项目名由 `compose.yml` 的 `name:` 决定,不要传 `-p`,否则会另建一套数据卷:
```sh
docker compose --env-file .local/container-test.env up --build -d
python3 scripts/container-smoke.py --phase create
# 重建全部容器,保留命名数据卷;不要加 down -v
docker compose --env-file .local/container-test.env up -d --force-recreate
python3 scripts/container-smoke.py --phase verify
```
`/blog` 公开页验收(登录 → 草稿不出现在匿名接口 → 发布后公开 → 删除测试文章):`python3 .local/stack-smoke.py`。2026-11-10 在 `myspace_hifox` 栈实测 6/6 通过;同次确认匿名接口带 `nosniff`、`X-Frame-Options: DENY` 等响应头。
2026-11-10 重启时实测:容器已移除但镜像保留时,`docker compose up` 直接运行**旧镜像**,不读源码;改了代码后必须 `docker compose --env-file .local/container-test.env build` 或加 `--build`,再用 `docker compose ... ps` 确认容器镜像 ID 与新镜像一致。.local/compose-e2e.py 依赖公开接口中的 slug(V3),在 V2 镜像上会报 `KeyError: 'slug'`。
`create` 验证静态页面、匿名拒绝、登录、CSRF、笔记 CRUD 与冲突、搜索筛选、文本/PNG 上传和下载、实际统计、退出及文件私有性。它将新建记录的 UUID 保存到 `.local/container-test-state.json`。
`verify` 重新登录,检查重建前的笔记版本和内容,按 SHA256 检查两个文件内容,随后只删除脚本创建的记录并检查统计回到基线。若中途失败,保留状态文件,排查后再次执行 `verify`;不要直接删除状态文件造成测试数据失去追踪。
## 首次启动值与已有数据卷
`DB_PASSWORD`(数据库角色)和 `ADMIN_PASSWORD`(唯一账户)只在**首次创建**时生效;已有数据卷时重建容器、修改 env 都不会改变它们。
2026-11-10 晚,`myspace_postgres-data` 卷是由先前一次以 `.env.example` 示例值启动的运行创建的:角色密码为 `replace-with-a-long-database-password`,账户 `admin` 的哈希对应示例密码 `replace-with-a-unique-password`。为与 `.local/container-test.env` 一致,角色密码已在单用户模式用 `ALTER ROLE` 重置,账户哈希已改写为 `ADMIN_PASSWORD` 的 BCrypt 值。未删除任何数据。
但工程根目录没有 `compose.yml` 的 `name:` 时,项目名取自目录名,当前由 `compose.yml` 使用的是 `myspace_hifox` 栈,其数据卷 `myspace_hifox_postgres-data` / `myspace_hifox_asset-data`。该卷同样由示例值创建,2026-11-10 重启时已把角色密码重置为 `DB_PASSWORD`、`admin` 哈希改写为 `ADMIN_PASSWORD`。目前线上数据只有 1 篇已发布文章。`myspace_postgres-data` / `myspace_asset-data` 中的示例值数据**未**重置,暂未被任何栈使用。
## 重置角色密码
在工程根目录执行;密码经环境变量传入,包含引号也安全(已实测):
```sh
set -a; . ./.env; set +a # 读取 DB_PASSWORD;也可换成任意密码
docker compose stop db
docker run --rm --user postgres -e NEWPW="$DB_PASSWORD" \
-v myspace_postgres-data:/var/lib/postgresql/data \
registry-1.docker.io/library/postgres:16-alpine \
sh -c 'printf "ALTER ROLE myspace PASSWORD %s;\n" "$(printf "%s" "$NEWPW" | sed "s/'"'"'/'"'"''"'"'/g; s/^/'"'"'/; s/$/'"'"'/")" | postgres --single -D /var/lib/postgresql/data postgres'
docker compose up -d
```
## 重置账户密码
`ADMIN_PASSWORD` 只在数据库中没有任何账户时生效。需要生成 BCrypt 哈希(`$2a$`,60 字符)后写入 `app_user`:
```sh
set -a; . ./.env; set +a
docker run --rm -e PW="$ADMIN_PASSWORD" registry-1.docker.io/library/maven:3.9-eclipse-temurin-21 sh -c 'mvn -q dependency:get -Dartifact=org.springframework.security:spring-security-crypto:6.5.6 >/dev/null 2>&1; cat > /tmp/G.java <<EOF
public class G { public static void main(String[] a){ System.out.print(org.springframework.security.crypto.bcrypt.BCrypt.hashpw(a[0], org.springframework.security.crypto.bcrypt.BCrypt.gensalt(10))); } }
EOF
CP=$(find ~/.m2 -name "spring-security-crypto-6.5.6.jar" | head -1); javac -cp "$CP" -d /tmp/c /tmp/G.java && java -cp "/tmp/c:$CP" G "$PW"' | tail -1 > /tmp/hash
[ "${#$(cat /tmp/hash)}" -eq 60 ] || { echo '哈希生成失败,未写入'; exit 1; }
printf "update app_user set password_hash = '%s' where id=1;\n" "$(cat /tmp/hash)" | docker exec -i myspace_hifox-db-1 psql -U myspace -d myspace
rm -f /tmp/hash
```
写完无需重启,下一次登录即生效。
## 本机镜像拉取问题
2026-11-10 首次测试时,Docker Desktop 全局配置中的镜像加速服务长时间未返回。测试通过 `IMAGE_REGISTRY=registry-1.docker.io` 直接从 Docker Hub 官方仓库拉取成功。项目增加了可选 `IMAGE_REGISTRY` 构建参数和数据库镜像前缀,默认仍为 `docker.io`;未修改 Docker Desktop 全局配置,也未关闭 TLS 校验。
首次构建需下载 Maven/JDK、JRE、Node、Nginx 和 PostgreSQL 基础镜像。后续构建复用 Docker 缓存。第一次后端构建下载 logback-classic 时遭遇 Maven Central 读取超时;后端 Dockerfile 已加入 BuildKit Maven 缓存挂载,失败后重试可复用已下载依赖。
## 服务维护
```sh
# 状态和日志
docker compose --env-file .local/container-test.env ps
docker compose --env-file .local/container-test.env logs --tail=100
# 后端健康状态
docker inspect myspace_hifox-backend-1 --format '{{.State.Health.Status}}'
# 停止并移除容器,保留数据卷
docker compose --env-file .local/container-test.env down
# 再次启动
docker compose --env-file .local/container-test.env up -d
```