docs: publish open-source guides and MIT license
This commit is contained in:
eezd committed
1 parent
1f01140b1d
commit
b1faab339e
10 files changed
+530
-86
No files matched your search
+86
@@ -0,0 +1,86 @@
|
||||
# API 与认证
|
||||
|
||||
[返回项目首页](../README.zh-CN.md) · [开发指南](development.md)
|
||||
|
||||
API 基础路径为 `/api/v1`。完整端点、请求字段、权限和响应以 [OpenAPI 源文件](../internal/api/openapi.json)为准，运行中的实例在 `GET /api/v1/openapi.json` 提供同一文档。测试 `TestOpenAPICoversRoutes` 核对路由覆盖。
|
||||
|
||||
## 脚本接入
|
||||
|
||||
在「设置 → 账户与安全 → API 令牌」创建只读或读写令牌。受保护 API 只接受 `Authorization: Bearer <token>`，不接受 Cookie，也不要将主令牌放进 URL。
|
||||
|
||||
以下只读示例从环境变量读取凭据：
|
||||
|
||||
```sh
|
||||
# 先在本机环境中设置 RAWMARK_URL 和 RAWMARK_TOKEN，不要提交真实值。
|
||||
curl --fail-with-body \
|
||||
-H "Authorization: Bearer $RAWMARK_TOKEN" \
|
||||
"$RAWMARK_URL/api/v1/tree"
|
||||
```
|
||||
|
||||
`rm_` API 令牌在服务端只存哈希，保留 read/write 权限。只读令牌可读取笔记、搜索和执行只读 POST 导出，不能写入；API 令牌不能管理账户、令牌、维护或资源票据，不能为自身扩权。管理操作需要浏览器登录会话。
|
||||
|
||||
## JSON 与 HTTP 语义
|
||||
|
||||
普通 JSON 成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": { "ok": true },
|
||||
"message": "成功"
|
||||
}
|
||||
```
|
||||
|
||||
`code = 0` 表示成功，非零表示失败；失败时 `message` 是可展示的原因。保留真实 HTTP 状态，不把错误全部转为 200。通用错误码为 HTTP 状态乘 100，特定业务码如下：
|
||||
|
||||
| HTTP | code | 含义 |
|
||||
| --- | --- | --- |
|
||||
| 400 | 40001 | 验证码错误、无效或已使用 |
|
||||
| 400 | 40002 | 验证码过期 |
|
||||
| 400 | 40003 | 修改密码时当前密码错误，不清理身份 |
|
||||
| 401 | 40101 | 登录密码错误 |
|
||||
| 412 | 41200 | 文件版本冲突，当前版本在 `data.rev` |
|
||||
|
||||
401 表示需要重新认证；403 表示当前身份没有权限，不能据此注销用户。维护输入或备份内容无效返回 400，占用或空间不足返回 503，文件系统/数据库内部故障返回 500。
|
||||
|
||||
**文件原文、下载、WebSocket、204 及 OpenAPI 文档不包 JSON 外壳**。`GET /files/{path}` 返回 Markdown 原文和 `ETag`；`PUT /files/{path}` 接收原文，成功返回包含 `rev` 的 JSON。用 `If-Match: "rev"` 防止覆盖新版本，或 `If-None-Match: *` 要求目标不存在；都不带会直接覆盖，不适合需要冲突保护的写入。
|
||||
|
||||
## 浏览器登录
|
||||
|
||||
实例没有用户名、注册或角色系统。尚未初始化时，`POST /auth/setup` 使用 `{ password }` 设置密码并返回会话；已经初始化的实例不能再次初始化。
|
||||
|
||||
正常登录流程：
|
||||
|
||||
1. `POST /auth/captcha` 获取 `{ captchaId, imageDataUrl, expiresAt }`。
|
||||
2. 展示图片，用户填写密码与六位数字验证码。
|
||||
3. `POST /auth/login` 提交 `{ password, captchaId, captchaCode }`。
|
||||
4. 成功返回 `{ token, expiresAt }`，再通过 `GET /auth/me` 恢复真实身份与权限。
|
||||
|
||||
以上字段均位于普通响应的 `data` 中。刷新验证码时传 `{ replaceId }` 使旧挑战失效。挑战绑定来源，五分钟过期；每次登录提交一次性消费，即使密码或验证码错误也不能重用，失败必须刷新。签发与登录均保留限流。
|
||||
|
||||
`rms_` 浏览器会话 Token 保存在 localStorage 的 `rawmark.token`，固定三十天有效、不滑动续期，服务端仅存哈希。退出调用 `POST /auth/logout`，服务端撤销成功返回 204 后才清理本地身份；请求失败时保留身份并提示错误，不能仅删除本地 Token 宣称注销完成。
|
||||
|
||||
localStorage 可被同源脚本读取；有完整前端权限的插件必须视为可信代码，不能承诺凭据隔离。
|
||||
|
||||
## 原生资源与事件
|
||||
|
||||
原生图片、字体、插件模块与浏览器 WebSocket 不能统一设置认证头，通过 `POST /auth/tickets` 获取受限资源 URL；主 Token 不进入 URL。票据服务端只保存哈希，每次读取检查父会话，父会话退出后即失效。
|
||||
|
||||
- 图片/字体票据不超过父会话有效期。
|
||||
- 插件票据额外绑定插件 ID 和版本，支持相对模块导入。
|
||||
- 事件握手票据一分钟有效、仅消费一次；已连接事件仍会检查父凭据。
|
||||
- 脚本 WebSocket 客户端可以通过 Bearer 请求头继续连接 `/api/v1/events`。
|
||||
|
||||
私有响应使用 `Cache-Control: no-store` 与 `Referrer-Policy: no-referrer`，API 和私有资源不进入 PWA 静态缓存。代理日志也需脱敏，见[部署文档](deployment.md#https-与反向代理)。
|
||||
|
||||
## 前端请求责任
|
||||
|
||||
请求处理、认证与路由守卫分别位于 `http/`、`pinia/` 和 `router/`。匿名跳登录并保留合法站内回跳，拒绝外部地址与循环跳转。401 清理当前身份、权限与动态路由，403 保留身份。
|
||||
|
||||
每次替换或退出会话更新代号、取消旧请求。用户信息、路由安装、异步响应与排队写入均须检查所属会话；旧结果按 Axios 取消语义拒绝，不能覆盖或注销新身份，也不提示取消错误。
|
||||
|
||||
同一错误只由一个责任层提示。请求默认负责展示，已有行内状态、保存重试或批量汇总的 API 使用 `errorOwner: 'caller'`；失败依然 reject，不以空列表或默认值伪装成功。
|
||||
|
||||
## 旧客户端迁移
|
||||
|
||||
统一协议需要前后端同时更新，不保留 Cookie/Bearer 或两种 JSON 格式兜底。旧 `rm_` API 令牌无需重建，但调用方要改为读取 `{ code, data, message }` 中的 `data`；文件及导出字节语义不变。旧浏览器页面需重新登录，不能连接新旧混用的后端。
|
||||
@@ -0,0 +1,119 @@
|
||||
# 部署与维护
|
||||
|
||||
[返回项目首页](../README.zh-CN.md) · [使用指南](guide.md) · [开发指南](development.md)
|
||||
|
||||
RawMark 将前端嵌入 Go 服务，运行时使用 SQLite 与文件系统，不需要额外数据库服务。目前从源码构建 Docker 镜像；以下命令不依赖预先发布的镜像仓库。
|
||||
|
||||
## Docker 快速启动
|
||||
|
||||
安装 Git、Docker 后：
|
||||
|
||||
```sh
|
||||
git clone https://github.com/eezd/RawMark.git
|
||||
cd RawMark
|
||||
docker build -t rawmark .
|
||||
docker run -d --name rawmark --restart unless-stopped \
|
||||
-p 127.0.0.1:21000:8080 \
|
||||
-v rawmark-data:/data \
|
||||
rawmark
|
||||
```
|
||||
|
||||
访问 http://localhost:21000 完成首次密码设置。命名卷 `rawmark-data` 保存应用数据，重新创建容器时应继续挂载同一个卷，不要删除它。服务器上的本机端口可通过 SSH 隧道访问，再完成初始化：
|
||||
|
||||
```sh
|
||||
ssh -L 21000:127.0.0.1:21000 user@your-server
|
||||
```
|
||||
|
||||
容器默认以 UID/GID `65532:65532` 运行，Docker 新建命名卷会继承镜像数据目录的权限。
|
||||
|
||||
## Docker Compose
|
||||
|
||||
仓库提供 [deploy/docker-compose.yml](../deploy/docker-compose.yml)，使用宿主机的 `deploy/data/` 持久化。Linux 上首次部署可执行：
|
||||
|
||||
```sh
|
||||
mkdir -p deploy/data
|
||||
sudo chown 65532:65532 deploy/data
|
||||
docker compose -f deploy/docker-compose.yml up -d --build --wait
|
||||
```
|
||||
|
||||
该配置默认发布到所有网卡的 **21000** 端口。对公网开放前完成初始化并设置访问边界；使用反向代理时，可将 Compose 端口绑定改为 `127.0.0.1:${RAWMARK_PORT:-21000}:8080`。自定义端口可使用 `RAWMARK_PORT=21001 docker compose -f deploy/docker-compose.yml up -d --build --wait`。
|
||||
|
||||
不要把快速开始中的容器与 Compose 实例同时指向同一份数据库或笔记库；切换部署方式前先停止旧实例、备份并确认数据位置。
|
||||
|
||||
## 存储与配置
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `RAWMARK_DATA` | `/data` | 应用数据库、索引、资源与默认笔记库所在目录 |
|
||||
| `RAWMARK_VAULT` | `$RAWMARK_DATA/vault` | Markdown 笔记库，可以单独挂载已有目录 |
|
||||
| `RAWMARK_ADDR` | `:8080` | 容器或二进制内部的监听地址 |
|
||||
|
||||
主要数据：
|
||||
|
||||
| 路径 | 内容 |
|
||||
| --- | --- |
|
||||
| `vault/` | Markdown 文件、附件与笔记库元数据；设定外置笔记库时位于对应目录 |
|
||||
| `rawmark.db` | 密码、会话、API 令牌、设置等应用状态 |
|
||||
| `index.db` | 可重建的搜索索引 |
|
||||
| `fonts/`、`themes/`、`plugins/` | 用户导入的字体、主题和插件 |
|
||||
| `backups/` | 导入或恢复操作前生成的回退备份 |
|
||||
| `logs/` | 运行日志 |
|
||||
|
||||
要接入已有文件夹，可额外挂载它并设置 `RAWMARK_VAULT`：
|
||||
|
||||
```sh
|
||||
docker run -d --name rawmark --restart unless-stopped \
|
||||
--user "$(id -u):$(id -g)" \
|
||||
-p 127.0.0.1:21000:8080 \
|
||||
-v "$HOME/rawmark-data:/data" \
|
||||
-v "$HOME/notes:/vault" \
|
||||
-e RAWMARK_VAULT=/vault \
|
||||
rawmark
|
||||
```
|
||||
|
||||
先创建 `$HOME/rawmark-data` 和 `$HOME/notes`，确保所选用户可写。此例以宿主机当前用户运行，适合管理自己的已有目录；不设置 `--user` 时须给容器默认用户写权限。RawMark 会修改笔记和链接，首次接入前请备份已有目录。
|
||||
|
||||
## HTTPS 与反向代理
|
||||
|
||||
远程访问使用 HTTPS。代理到 RawMark 时需要转发 Host、协议与来源地址，并启用 WebSocket 升级和长连接；浏览器事件连接使用 `/api/v1/resources/<ticket>/events/`。代理上传限制也应满足实际导入需求。
|
||||
|
||||
[仓库 Nginx 配置](../deploy/nginx/raw.134333.xyz.conf)包含 WebSocket 和票据日志脱敏示例，但其中域名、证书 include、反爬 include、端口及日志路径属于原部署环境，**需要按自己的服务器调整，不能原样安装**。`$connection_upgrade` 的 map 也需要在 Nginx 的 `http` 上下文定义。
|
||||
|
||||
资源票据是凭据：代理、CDN 和访问日志不得记录明文票据、查询参数或携带凭据的 Referer；应用的 `no-store` 不能代替代理日志脱敏。Nginx 错误日志也可能包含原始请求路径，仓库示例对票据资源路径关闭错误日志，保留脱敏访问日志及应用错误日志。
|
||||
|
||||
若使用 CDN，需独立完成自定义域名与 TLS 证书配置，并确认 API、私有资源和 WebSocket 不被错误缓存；仅配置 DNS 不代表 HTTPS 接入已完成。
|
||||
|
||||
## 备份与恢复
|
||||
|
||||
在「设置 → 存储空间」选择所需导出类型：
|
||||
|
||||
| 类型 | 适合用途 | 恢复行为 |
|
||||
| --- | --- | --- |
|
||||
| 普通 Markdown 笔记库 | 迁移到其他笔记工具 | 导入到新文件夹，不替换实例 |
|
||||
| 设置与资源 | 迁移偏好、插件数据、字体/主题/插件 | 合并资源，同 ID 替换，包外资源保留 |
|
||||
| 完整实例 | 迁移或恢复 RawMark | 替换业务数据，包含登录信息、回收站和资源，完成后重新登录 |
|
||||
|
||||
设置导入与完整恢复只接受本程序的版本化 ZIP，应用前会在 `backups/` 保留回退包。上传顺序分块，每块 8 MiB，压缩包上限 2 GiB，展开上限 8 GiB、100000 项。不包含运维环境配置、派生索引或临时文件。
|
||||
|
||||
完整恢复前停止其他程序直接改写笔记库。维护时暂时暂停 API 操作，关闭数据库和后台任务后恢复，中断时回退操作前备份。导出的完整包包含账户和笔记等敏感数据，应妥善保管，不提交到仓库或附在公开 Issue 中。
|
||||
|
||||
独立于应用备份，升级前建议停止服务后备份完整数据目录、外置笔记库、部署配置与旧镜像。SQLite 运行时可能有 WAL 文件，不要只复制正在写入的 `rawmark.db` 来冒充一致备份。
|
||||
|
||||
## 升级与回退
|
||||
|
||||
1. 确认目标版本的行为和数据兼容性，保留当前镜像及部署配置。
|
||||
2. 停止旧服务，备份应用数据与外置笔记库。
|
||||
3. 更新源码并重新构建，使用同一份挂载启动新实例；不要并行运行新旧服务。
|
||||
4. 核对容器健康、登录、笔记与附件。回退时使用配套的旧镜像与数据备份。
|
||||
|
||||
Bearer 认证升级需要前后端一起发布。旧 Cookie 页面不能继续使用，需重新登录；启动程序会沿现有 SQLite 初始化流程创建资源票据表和索引，笔记、密码、设置与已有 API 令牌保留。第三方客户端的 JSON 解包方式须遵循[当前协议](api.md)。
|
||||
|
||||
`scripts/remove-sharing.sql` 和 `scripts/reset-shortcuts.sql` 是历史版本的一次性迁移：前者移除旧分享数据，后者清空旧快捷键覆盖。**新部署无需运行，已执行过的实例不要重跑**；只有确认来自对应旧版本且需要该迁移时，才在停服并备份后单独执行。
|
||||
|
||||
## 日常维护与排查
|
||||
|
||||
- 容器自带健康检查，也可访问 `GET /api/v1/health`；健康不代表所有业务流程已验证。
|
||||
- 设置内的优化/重建仅处理派生索引；清理临时文件不删除用户文件、活动上传或恢复备份。
|
||||
- 重置设置保留账户、资源、插件存储和本机标签页。
|
||||
- 日志位于 `logs/`，轮转保留三份，每份至多 10 MiB；可在设置中导出日志及版本摘要。该功能不补录历史日志。
|
||||
- 更新后界面异常先核对前后端是否来自同一构建，再查看浏览器网络请求和应用日志；插件与外观恢复入口见[使用指南](guide.md#插件与界面恢复)。
|
||||
@@ -0,0 +1,99 @@
|
||||
# 开发指南
|
||||
|
||||
[返回项目首页](../README.zh-CN.md) · [API 与认证](api.md) · [项目约束](../AGENTS.md)
|
||||
|
||||
## 工具链
|
||||
|
||||
- Go 1.27.2 或更高版本，具体要求见 [go.mod](../go.mod)。
|
||||
- Node.js 24+、pnpm **12.11.2**；前端依赖以 [pnpm-lock.yaml](../web/pnpm-lock.yaml) 为准。
|
||||
- Docker 仅在验证容器构建或部署时需要，本地开发不强制使用。
|
||||
|
||||
前端采用 Vue 3、TypeScript、Vite、Router、Pinia、Element Plus、Axios、SCSS 与 UnoCSS；编辑器使用 CodeMirror 6。服务端使用 Go 标准库 HTTP、SQLite 与文件系统；Markdown 文件是真源，搜索索引可以重建。
|
||||
|
||||
## 启动本地开发
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
corepack prepare [email protected] --activate
|
||||
scripts/dev.sh
|
||||
```
|
||||
|
||||
脚本使用锁文件安装前端依赖，同时启动 Go 开发服务和 Vite 热更新。打开 http://localhost:5173，首次访问初始化密码；Ctrl+C 同时退出。
|
||||
|
||||
```sh
|
||||
scripts/dev.sh --host # 允许局域网设备访问前端
|
||||
scripts/dev.sh --help
|
||||
```
|
||||
|
||||
`RAWMARK_DATA` 默认指向仓库的 `.dev-data/`，`API_PORT` 默认 8080，`WEB_PORT` 默认 5173。可通过环境变量覆盖，例如 `API_PORT=18080 WEB_PORT=15173 scripts/dev.sh`。不要将开发服务指向生产数据；初始化、恢复、导入和删除测试只使用合成数据。
|
||||
|
||||
开发模式从源码统计可选字体，日志版本显示为 `dev`，不读取旧 `web/dist`。生产模式使用嵌入的前端构建、字体清单和构建版本。
|
||||
|
||||
## 目录职责
|
||||
|
||||
```text
|
||||
cmd/rawmark/ 服务入口
|
||||
internal/
|
||||
api/ HTTP 路由、授权、协议及 OpenAPI
|
||||
auth/ 密码、会话与 API 凭据
|
||||
store/ 应用 SQLite
|
||||
vault/ 真源笔记、附件与文件操作
|
||||
search/ 可重建的派生索引
|
||||
web/
|
||||
src/
|
||||
pages/login/ 初始化与验证码登录
|
||||
pages/workspace/ 笔记、目录、编辑器与图片管理
|
||||
pages/settings/ 设置、账户与维护
|
||||
common/apis/ 全部资源 API
|
||||
common/components/ 跨模块公共组件
|
||||
common/ 共享外观、Markdown、插件 SDK 与工具
|
||||
http/ Axios、认证头、统一响应与错误
|
||||
router/ 路由与守卫
|
||||
pinia/ 实例及共享认证、权限、设置状态
|
||||
types/auto/ 自动生成的导入声明
|
||||
deploy/ 容器与代理配置
|
||||
scripts/ 开发、资源生成及历史迁移脚本
|
||||
```
|
||||
|
||||
页面私有组件、类型、状态、组合函数和资源跟随 `pages/<module>/`，确实跨模块复用的能力才进入 `common`；公共代码不得依赖页面私有实现。模块内优先相对导入，跨职责用 `@`（`web/src`）与 `@@`（`web/src/common`）。
|
||||
|
||||
全部资源接口位于 `common/apis/<resource>/index.ts` 和 `type.ts`。函数直接调用 `request<ResponseData>({ url, method, data, params })`，返回完整 `{ code, data, message }`，调用方显式读取 `.data`。原文/下载设置 `returnResponse: true` 保留 Axios 响应与响应头，204 返回 void，事件连接也归资源 API。不增加页面私有请求入口或多格式 fallback。
|
||||
|
||||
公共组件放在 `common/components/<PascalCaseName>/index.vue`。SFC 使用 Composition API 与 TypeScript，其他文件使用 kebab-case。自动声明应修改生成配置后重新构建，不手工编辑。更完整的执行约束以根 [AGENTS.md](../AGENTS.md) 为准，不另维护一套规范。
|
||||
|
||||
## 验证
|
||||
|
||||
```sh
|
||||
pnpm -C web install --frozen-lockfile
|
||||
pnpm -C web lint:check
|
||||
pnpm -C web typecheck
|
||||
pnpm -C web test
|
||||
pnpm -C web build
|
||||
go vet -tags dev ./...
|
||||
go test ./internal/...
|
||||
go test -tags dev ./web
|
||||
```
|
||||
|
||||
前端使用 Vitest，测试随模块存放；Go 使用标准 `testing`。生产构建需先生成 `web/dist`，Go 再将其嵌入二进制。`-tags dev` 保留无需嵌入产物的开发和对应测试边界。
|
||||
|
||||
按改动风险补充 Go race、Docker 构建及真实浏览器验收。认证与请求变更应覆盖验证码成功/失败/过期、401 与 403、服务端注销以及旧会话响应隔离；编辑器与文件操作应核对原文保存、版本冲突、附件及移动/导入/导出。不用空数据或模拟成功掩盖失败。
|
||||
|
||||
## 主题、字体与插件
|
||||
|
||||
内置默认、白色与黑色主题，保留独立明暗模式和 CSS 片段。自定义主题位于数据目录 `themes/<id>/`，包含 `manifest.json` 与 `theme.css`；清单包含 `id`、`name`、`version`，ID 与目录一致，不能覆盖保留的 `default`、`white`、`black`。在外观设置刷新列表后选择。
|
||||
|
||||
默认字体资源已入库，常规构建无需下载或转换。重新生成时，在独立 Python 环境安装 `fonttools[woff]`，下载 [Maple v7.9 指定字体包](https://github.com/subframe7536/maple-font/releases/download/v7.9/MapleMonoNormalNL-NF-CN.zip)，执行：
|
||||
|
||||
```sh
|
||||
python3 scripts/prepare-maple-font.py /path/to/MapleMonoNormalNL-NF-CN.zip
|
||||
```
|
||||
|
||||
脚本生成 WOFF2 和 `maple-font.css`，保留上游许可。代码块使用 highlight.js 的固定 Atom One Dark，不能在更新主题时顺带恢复旧高亮实现或配色。
|
||||
|
||||
插件 SDK 类型见 [common/plugin-api/index.d.ts](../web/src/common/plugin-api/index.d.ts)，加载与生命周期实现位于 `common/plugins/`。插件仅在前端运行，安装者必须信任其代码；命名空间、停用及资源版本管理不等于权限沙箱。编辑器扩展故障时保留正文并停用当前页相关扩展。
|
||||
|
||||
## 提交改动
|
||||
|
||||
先阅读 [AGENTS.md](../AGENTS.md)，聚焦实际需求，保留必要契约，不机械照搬模板示例。前端目录以 [vue3-starter 固定基线](https://github.com/eezd/vue3-starter/tree/fd41d62ce3f1c8338a478e0be3e2f31b53b7ea5e) 为参考，RawMark 的编辑器、主题和专用交互按业务保留。
|
||||
|
||||
提交前运行适用检查，说明实际验证与未验证范围。Commit 使用清晰英文，按功能拆分；不要提交真实笔记、账户数据、密钥或本地交接文件。
|
||||
@@ -0,0 +1,67 @@
|
||||
# 使用指南
|
||||
|
||||
[返回项目首页](../README.zh-CN.md) · [部署与维护](deployment.md) · [API 与认证](api.md)
|
||||
|
||||
RawMark 是单用户笔记工作台，笔记保存在服务器上。多个浏览器可以访问同一个实例；它不是多人协作系统，目前没有公开分享功能。
|
||||
|
||||
## 开始写作
|
||||
|
||||
首次访问设置密码，之后通过密码和图片验证码登录。在侧栏「文件目录」标题或空白处右键，可以搜索、新建笔记、新建目录、导入文档、打开标签索引或管理图片；点击标题同样可以打开菜单，便于触屏使用。
|
||||
|
||||
编辑器默认使用即时预览，点击右上角图标切换源码模式、打开大纲或进入专注写作。支持标准 Markdown、表格、任务列表、代码块、数学公式、Mermaid、脚注和 YAML 元数据。
|
||||
|
||||
正文修改自动保存，保存失败或版本冲突会明确提示。外部程序修改笔记时会同步到页面；出现冲突时请核对内容，不要直接覆盖仍需保留的版本。
|
||||
|
||||
选中文字后可使用外观、加粗、斜体、下划线、删除线、高亮与链接。局部外观和下划线以受限的标准 HTML 标签存入 Markdown，源码和导出会保留；其他阅读器是否呈现这些样式取决于其 HTML 支持。
|
||||
|
||||
## 整理笔记
|
||||
|
||||
- **文件与文件夹**：右键重命名、移动、删除或导出。拖到文件夹行会移入该文件夹，拖到笔记行会移入该笔记所在目录。
|
||||
- **多选**：Ctrl/Cmd 点击切换选择，Shift 点击选择可见范围，再通过右键菜单批量操作。部分操作失败会逐项报告。
|
||||
- **标签页**：支持固定和关闭其他标签；固定标签不会被「关闭其他标签页」关闭。打开的标签及固定状态在当前浏览器保存，刷新或重启后恢复。
|
||||
- **图标**：文件夹默认 📂、文件默认 📄，点击图标或右键「修改图标」选择表情或内置图标。
|
||||
- **标签和搜索**：正文 `#标签`、YAML `tags` 可用于归类；全文搜索用于查找笔记。文章标题生成右侧大纲。
|
||||
|
||||
应用内重命名和移动会维护笔记中的本地链接与图片引用。直接在文件系统中操作时，不保证链接、图标等元数据跟随；这些操作优先在 RawMark 内完成。
|
||||
|
||||
## 导入与导出
|
||||
|
||||
在目录或文件夹菜单选择「导入」，支持多个 UTF-8 `.md` 文件或单个 ZIP，总上传上限为 100 MiB。
|
||||
|
||||
ZIP 会导入到同名新文件夹，保留笔记层级。本地图片归入各笔记同级的 `assets/`，并改写引用；同名不同内容不会覆盖。缺失的本地链接会提示，远程图片不会自动下载。可以用思源笔记等工具导出的 Markdown ZIP 迁入，具体排版仍取决于其 Markdown 内容。
|
||||
|
||||
导出时，单篇无附件笔记直接下载 `.md`；其他情况下载保留层级、原文与本地附件的 ZIP，不下载远程资源。选中项存在缺失附件时会报错，便于先修复再导出。
|
||||
|
||||
整个笔记库的普通 Markdown 导出在「设置 → 存储空间」，缺失附件记录于导出包的 `.rawmark-export/missing-assets.json`。这个报告不会在重新导入时成为笔记。
|
||||
|
||||
## 图片管理
|
||||
|
||||
粘贴、上传和导入的图片默认保存在笔记同级的 `assets/`，同目录相同内容去重，正文使用相对路径。侧栏隐藏附件目录，右键文件夹选择「图片管理」即可查看，也可切换整个知识库。
|
||||
|
||||
图片管理提供检索、排序、网格/列表、批量上传、预览、引用查看、重命名、移动和替换。重命名或移动会更新笔记引用；替换保留路径，要求相同扩展名、最大 50 MiB，旧图片不会进入回收站。
|
||||
|
||||
笔记跨目录移动时图片跟随，仍被其他笔记引用的原图保留。**删除单篇笔记不会顺便删除共享图片**。清理孤立图片会先展示候选，再核对全库引用，将符合条件的图片移入回收站。旧版 `笔记名.assets/` 附件目录仍可读取、移动与恢复。
|
||||
|
||||
## 外观、字体与快捷键
|
||||
|
||||
在「设置 → 外观」切换明暗模式、主题，调整界面字体和字号、玻璃透明度或 CSS 片段；正文与代码字体、正文宽度、行高等位于编辑器设置。设置保存在服务器，多个设备共享；标签页等本机状态单独保存。
|
||||
|
||||
默认字体为 Maple Mono Normal NL NF CN v7.9，不可删除。界面、正文和代码可分别选择字体，各字体选择器支持导入 TTF、OTF、WOFF、WOFF2（单个不超过 30 MiB）及删除导入字体。页面等待所需字体加载后显示，失败会提示刷新。代码块固定使用 highlight.js 的 Atom One Dark，与页面明暗模式独立。
|
||||
|
||||
快捷键默认参考 Typora 的 Windows/Linux 或 macOS 组合，无对应项及插件命令默认留空。可以搜索、添加、逐条删除、单项或全部重置，冲突绑定会被拒绝。Ctrl/Cmd+1～6 设置对应标题，再次触发同级标题恢复正文；浏览器保留键可自行改绑。
|
||||
|
||||
手机设置采用分类和内容两级布局。应用安装入口位于「设置 → 关于」；PWA 缓存静态外壳，**不代表支持离线编辑与离线同步**。
|
||||
|
||||
## 回收站与存储空间
|
||||
|
||||
删除的内容进入回收站，支持恢复和清空全部。默认保留 30 天，设置为 0 则不自动删除；修改期限同样影响已有条目，清理在启动时及每小时执行。
|
||||
|
||||
「存储空间」自动展示数据目录、外置笔记库和可选字体占用；字体统计不含默认 Maple，附件与回收站计入笔记库。这里还可导出/导入完整实例、笔记和设置，优化/重建索引、清理临时文件、重置设置及导出日志。
|
||||
|
||||
完整实例恢复会替换当前业务数据并要求重新登录；替换前请先备份，具体范围、限制与恢复注意事项见[部署与维护](deployment.md#备份与恢复)。
|
||||
|
||||
## 插件与界面恢复
|
||||
|
||||
插件由实例管理者安装，属于有完整前端权限的扩展，请只安装可信来源；不提供沙箱隔离保证。开发入口见[开发指南](development.md#主题字体与插件)。
|
||||
|
||||
插件导致界面异常时，可在地址后加 `?disable-plugins` 暂停插件并进入管理。主题或 CSS 片段导致界面不可用时，可加 `?reset-appearance` 临时停用自定义外观，再进入设置恢复默认。这些入口不自动删除笔记或丢弃编辑内容。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
Reference in new issue
Block a user