HiFox Agent a60ea8d262 fix(XZH-21): align note history to notes.version, wire inbox into unified trash, migrate history on category delete
- NotesController: snapshot written under result version; history/{version} no longer falls back to current content; DBG removed
- V18: legacy_versioning flag so pre-upgrade history keeps its numbering
- NoteCategoriesController: migrate notes + history on category delete (includes trashed notes), snapshot at result version
- InboxController/TrashService/AdminToolsController: inbox items soft delete, restore, purge; recapture revives trashed item
- PlannerController batch tags scoped by kind; Dashboard taskCounts.due shares today-tasks filter
- Tests: 34 passing (3 new regression cases)
2026-11-11 20:50:40 +08:00

MySpace

新版界面以 MySpace V4 开发交接 为参考。管理页支持 /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/数据库映射和后续五阶段计划见 实施计划。

已实现

  • 工作台、登录、全局搜索和深浅色主题。
  • 知识库包含文件夹、分类、多标签、模板、列表和网格、批量管理、双链、反向链接及图谱。编辑器自动保存,支持版本预览、恢复和带元数据的 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:

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 容器需先停止):

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,见 容器验收 的「重置账户密码」。

默认仅绑定回环地址,本机访问使用 HTTP;若配置外部 HTTPS 入口,将 COOKIE_SECURE=true。后端不直接暴露端口,前端 Nginx 同源代理 API。尚未提供公网部署加固、登录限速、MFA 或自动备份。2026-11-10 已在 Docker Desktop 上完成前后端镜像构建、Compose 启动、28 项接口/持久化检查及浏览器验证;详见 容器验收。

本机开发

需要 Java 21、Maven 3.9+、Node 22.13+(本机验证 Node 24)、PostgreSQL 16。创建 myspace 数据库和有权限的专用角色。

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 同时启动前后端(数据库需先启动)。

另开终端:

cd frontend
npm ci
npm run dev

打开 http://localhost:5173 。Vite 将 /api 转发到 127.0.0.1:8080。首次启动由 Flyway 建表,然后初始化账户。空数据库启动时必须提供有效密码,否则启动失败。

当前 Mac 的默认 Java 是 8,应先设置:

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,切勿指向业务数据库。

# 先创建 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) 图片保留和外部链接新标签页打开。浏览器验收记录见 验证记录。

API 与数据

见 API 说明。第二版迁移 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 文档:登录及退出后重新获取 CSRF token。前端运行环境参考 Vite 官方说明。

S
Description
No description provided
Readme
3.8 MiB
0 Stars 1 Watchers 0 Forks
Languages
Java 47.3%
Vue 40.1%
CSS 4.6%
Python 3.5%
TypeScript 2.3%
Other 2.2%