Files

121 lines
9.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/)。