WIP: XZH-21 后端改动 + 测试验收附加用例
This commit is contained in:
commit
1bd637528d
168 files changed
+13874
No files matched your search
@@ -0,0 +1,120 @@
|
||||
# MySpace
|
||||
|
||||
新版界面以 [MySpace V4 开发交接](docs/v4-development.md) 为参考。管理页支持 `/admin/notes`、`/admin/blog`、`/admin/assets`、`/admin/bookmarks` 等直接访问。公开博客使用双栏文章和侧栏索引,支持分类、全文搜索与 RSS。公开导航提供分类书签和搜索。公开 AI 工作台位于 `/ai`,当前为访客界面预览。
|
||||
|
||||
基于实际 HTML 原型实现的个人知识与数字资产平台。Java 21 + Spring Boot 3 模块化单体,Vue 3 + TypeScript + Vite + Element Plus,PostgreSQL 16 + Flyway,单用户,REST `/api/v1`。
|
||||
|
||||
源原型位于 `/Users/xzh/Documents/MySpace/prototype`,保持原样。工程位于 `/Users/xzh/Documents/project/MySpace`。详细页面/API/数据库映射和后续五阶段计划见 [实施计划](docs/implementation-plan.md)。
|
||||
|
||||
## 已实现
|
||||
|
||||
- 工作台、登录、全局搜索和深浅色主题。
|
||||
- 知识库包含文件夹、分类、多标签、模板、列表和网格、批量管理、双链、反向链接及图谱。编辑器自动保存,支持版本预览、恢复和带元数据的 Markdown 导出。
|
||||
- 博客支持分类、草稿与已发布状态、笔记和博客互转、网络或图床封面、Markdown 即时预览与整篇预览。
|
||||
- 图床包含图片管理、文件管理、存储概览、文件夹、分类与标签、批量整理、素材元数据编辑,以及 URL、Markdown、HTML 和 BBCode 引用。
|
||||
- 书签包含常用收藏、手动顺序、标签、图标和打开方式设置、批量管理、HTML/JSON 导入预览与导出。
|
||||
- 书签和文件信息可转入收集箱,保留来源和整理状态。
|
||||
- 四个模块均有回收站。素材恢复后保留原链接,仍有引用的素材无法永久删除。
|
||||
- 「公开发布」以服务器快照同步博客与勾选的书签。已公开内容的普通编辑等待再次同步;文章转草稿、移入回收站或取消书签公开后立即撤回。已存在的公开链接沿用原地址。
|
||||
|
||||
## 后台 V4
|
||||
|
||||
- 工具中心含标签、版本、统一回收站、批量管理、工作流、浏览器工具和联动说明,均可单独打开。
|
||||
- RSS 可管理订阅、手动获取公开 RSS/Atom、阅读和收藏,并转存到收集箱、笔记或待办。仅在本机网络返回合成 DNS 地址时,使用 `RSS_PUBLIC_DNS` 指定的公开解析服务获取真实公网地址。
|
||||
- 效率中心提供待办、月历和代码片段。收集箱支持手动收集、浏览器书签收集和去重转存。
|
||||
- 设置支持个人资料、主题、自动保存偏好,以及有预览的非覆盖式 JSON 导入。备份导出包含文件清单,附件内容需另行备份。
|
||||
- AI Studio 的历史、素材、提示词、模型、用量和日志接入真实数据。可在部署环境设置 `AI_BASE_URL`、`AI_API_KEY`、`AI_CHAT_MODELS`、`AI_IMAGE_MODELS`,其中模型列表使用逗号分隔。支持 Chat Completions 和返回 PNG Base64 的 Images API。密钥只留在服务端。公开发布面板支持选择公开提示词和生成图片,访客生成当前关闭。
|
||||
|
||||
## Docker Compose 运行
|
||||
|
||||
需要 Docker Engine / Docker Desktop 和 Compose v2:
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
# 必须在首次启动前编辑 .env:设置独立的数据库密码和 12–72 字符的账户密码
|
||||
# 不要使用示例值作为实际密码(示例密码仍可通过登录校验)
|
||||
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
Compose 项目名固定为 `myspace`(`compose.yml` 中的 `name:`),无论目录名如何。首次启动时 `DB_PASSWORD` 决定数据库角色密码,`ADMIN_PASSWORD` 决定初始账户密码;容器重建**不会**修改已有的角色密码和账户密码,修改 `.env` 后需手动重置,见下。启动顺序为 db → backend(健康检查通过)→ frontend;后端的健康检查只探测 8080 端口可连接,首启动(Flyway 迁移 + 账号初始化)大约需要 10 秒。
|
||||
|
||||
打开 http://localhost:8088 ,使用 `.env` 中的 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD`。数据库和文件分别保存在命名卷 `myspace_postgres-data`、`myspace_asset-data`。`docker compose down` 保留数据;不要随意使用 `down -v`。修改初始化环境变量不会修改数据库内的账户密码。没有密码重置界面。
|
||||
|
||||
已有数据卷时修改密码(不删除数据;在工程根目录执行,`db` 容器需先停止):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
账户密码需要重新生成 BCrypt 哈希后写入 `app_user`,见 [容器验收](docs/container-testing.md) 的「重置账户密码」。
|
||||
|
||||
默认仅绑定回环地址,本机访问使用 HTTP;若配置外部 HTTPS 入口,将 `COOKIE_SECURE=true`。后端不直接暴露端口,前端 Nginx 同源代理 API。尚未提供公网部署加固、登录限速、MFA 或自动备份。2026-11-10 已在 Docker Desktop 上完成前后端镜像构建、Compose 启动、28 项接口/持久化检查及浏览器验证;详见 [容器验收](docs/container-testing.md)。
|
||||
|
||||
## 本机开发
|
||||
|
||||
需要 Java 21、Maven 3.9+、Node 22.13+(本机验证 Node 24)、PostgreSQL 16。创建 `myspace` 数据库和有权限的专用角色。
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
# 修改 DB_URL / DB_USER / DB_PASSWORD / ADMIN_PASSWORD
|
||||
set -a
|
||||
. ./.env
|
||||
set +a
|
||||
mvn -f backend/pom.xml spring-boot:run
|
||||
```
|
||||
|
||||
也可在配置 `.env` 后运行 `./scripts/dev.sh` 同时启动前后端(数据库需先启动)。
|
||||
|
||||
另开终端:
|
||||
|
||||
```sh
|
||||
cd frontend
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
打开 http://localhost:5173 。Vite 将 `/api` 转发到 `127.0.0.1:8080`。首次启动由 Flyway 建表,然后初始化账户。空数据库启动时必须提供有效密码,否则启动失败。
|
||||
|
||||
当前 Mac 的默认 Java 是 8,应先设置:
|
||||
|
||||
```sh
|
||||
export JAVA_HOME=/Applications/ServBay/package/openjdk/21/21.0.10/zulu-21.jdk/Contents/Home
|
||||
export PATH="$JAVA_HOME/bin:$PATH"
|
||||
```
|
||||
|
||||
本次本地验证的独立 PostgreSQL 数据目录为 `.local/pgdata`,监听 `127.0.0.1:55432`,开发角色 `myspace`,仅用于本机验证、使用 trust 认证,不适用于部署。日志为 `.local/backend.log`、`.local/frontend.log`、`.local/postgres.log`。停止验证数据库可执行 `pg_ctl -D .local/pgdata stop`(使用 PostgreSQL 16 工具)。
|
||||
|
||||
## 构建与测试
|
||||
|
||||
后端集成测试使用真实 PostgreSQL,不使用 H2。**必须准备独立测试数据库**;测试会清空 `notes`、`assets` 和 `blogs`,切勿指向业务数据库。
|
||||
|
||||
```sh
|
||||
# 先创建 myspace_test 数据库
|
||||
export TEST_DB_URL=jdbc:postgresql://localhost:55432/myspace_test
|
||||
export TEST_DB_USER=myspace
|
||||
export TEST_DB_PASSWORD=''
|
||||
export DB_PASSWORD=unused
|
||||
mvn -f backend/pom.xml verify
|
||||
npm --prefix frontend ci
|
||||
npm --prefix frontend test
|
||||
npm --prefix frontend run build
|
||||
```
|
||||
|
||||
测试账户固定为 `admin / integration-test-password`,仅存在于测试库;测试资产在 `backend/target/test-assets`。
|
||||
|
||||
后端 4 组集成测试覆盖未认证拒绝、登录失败、CSRF 拒绝、退出、密码散列、笔记完整 CRUD、输入校验、版本冲突、工作台聚合、私有文件上传/跨会话读取/下载/删除,以及博客的默认草稿、状态切换、状态筛选、搜索、版本冲突、非法状态和删除;公开博客只暴露已发布文章、草稿 slug 返回 404、匿名可读且不返回内部字段、ETag 条件请求返回 304。前端 5 项测试覆盖 Markdown 渲染、脚本及危险链接清理、原始 HTML 媒体/容器标签移除、http(s) 图片保留和外部链接新标签页打开。浏览器验收记录见 [验证记录](docs/verification.md)。
|
||||
|
||||
## API 与数据
|
||||
|
||||
见 [API 说明](docs/api.md)。第二版迁移 `V2__blogs.sql` 新增 `blogs` 表(status 有 CHECK 约束,按状态+更新时间建索引);第三版迁移 `V3__public_blogs.sql` 为文章增加唯一 `slug` 并回填历史文章。代码按 `auth`、`notes`、`blogs`、`assets`、`dashboard`、`common` 分包;`PublicBlogsController` 提供公开只读接口,`common/SecurityHeaders` 统一输出 `X-Content-Type-Options`、`Referrer-Policy`、`X-Frame-Options`。所有业务模块在同一进程内运行,共用一个数据库。第一版使用 Spring JDBC 参数化 SQL,迁移文件在 `backend/src/main/resources/db/migration`。
|
||||
|
||||
文件以随机 UUID 保存,客户端文件名不参与存储路径;不执行上传内容。数据库与文件系统不具备跨介质事务保证,进程崩溃时可能产生孤立文件或缺失内容;缺失文件返回 404。备份必须同时保存 PostgreSQL 和资产目录,后续阶段实现备份/恢复及清理任务。
|
||||
|
||||
认证实现参考 [Spring Security CSRF 文档](https://docs.spring.io/spring-security/reference/servlet/exploits/csrf.html):登录及退出后重新获取 CSRF token。前端运行环境参考 [Vite 官方说明](https://vite.dev/guide/)。
|
||||
Reference in new issue
Block a user