76 lines
7.8 KiB
Markdown
76 lines
7.8 KiB
Markdown
# RawMark
|
||
|
||
纯 Markdown 笔记网页编辑器：所见即所得（类 Obsidian Live Preview）、文件即真源、Docker 部署、浏览器访问。
|
||
|
||
## 部署
|
||
|
||
本机部署沿用 `/srv/AlphaPulse/deploy` 的目录约定，端口按 `/docker/main/.env` 的个人项目范围（21000–21999）分配为 `RAWMARK_PORT=21000`：
|
||
|
||
```sh
|
||
cd deploy
|
||
install -d -m 750 -o 65532 -g 65532 data
|
||
docker compose --env-file /docker/main/.env up -d --build --wait
|
||
```
|
||
|
||
持久化数据位于 `deploy/data/`，与 `.dev-data/` 独立。首次打开网页时直接设置登录密码。
|
||
升级已有实例移除分享时，先备份数据与旧镜像、停止旧服务，再对 `rawmark.db` 执行一次 `scripts/remove-sharing.sql`，然后启动新版本。脚本删除分享表、专用密钥及分享快捷键；不会删除笔记或图片。旧分享页面和接口返回 404。回滚必须配套恢复数据库和旧镜像，不能只恢复旧程序。
|
||
宿主机 Nginx 配置为 `deploy/nginx/raw.134333.xyz.conf`，复用现有通配证书及 WebSocket 升级映射；安装到 `/etc/nginx/conf.d/134333.xyz/` 后，先执行 `nginx -t` 再重载。
|
||
域名 `raw.134333.xyz` 在 DNSPod 设置 CNAME 指向 `cdn.134333.xyz`（与 AlphaPulse 一致）；还需在 Cloudflare for SaaS 的 `unino.top` 区域添加该自定义域名，并等待域名与托管证书均为 `active`。仅设置 CNAME 或旧区域中的 A 记录不足以完成 CDN 接入。访问地址为 `https://raw.134333.xyz`。修改端口时需同步端口登记和 Nginx 上游。
|
||
|
||
其他服务器也可直接构建并运行：
|
||
|
||
```sh
|
||
mkdir -p ~/rawmark-data
|
||
docker build -t rawmark .
|
||
docker run -d --name rawmark \
|
||
--user "$(id -u):$(id -g)" \
|
||
-p 8080:8080 \
|
||
-v ~/rawmark-data:/data \
|
||
--restart unless-stopped \
|
||
rawmark
|
||
```
|
||
|
||
- 首次打开直接设置登录密码，之后凭密码登录；请在将新实例开放给他人访问前完成初始化。
|
||
- 笔记以普通 `.md` 文件保存在 `数据目录/vault/`，粘贴、上传和导入的图片统一存放在笔记同级的 `assets/`，链接使用 `./assets/文件名`，同目录相同内容去重。笔记跨目录移动时图片跟随，仍被其他笔记引用的原图保留；删除单篇笔记不会删除共享图片。旧 `笔记名.assets/` 仍可读取、移动与恢复；外部修改会实时同步到网页。
|
||
- 知识工具：标准 Markdown 链接构成图谱，支持正文 `#标签` 与 YAML `tags`。笔记或文件夹在应用内改名、移动时维护入链和相对出链；公式和代码示例不参与关系提取。
|
||
- 日记与模板：默认日记路径为 `Daily/YYYY-MM-DD.md`（本地日期），已有日记直接打开；模板为 `Templates/` 下的普通 Markdown，支持 `{{date}}`、`{{time}}`、`{{title}}`，资源链接按新笔记位置调整。可在设置中修改目录和日记模板。
|
||
- 外观：浅色玻璃工作台与深色模式，默认字体为 Maple Mono Normal NL NF CN v7.9（界面、正文与代码），字体资源随应用本地提供，文字在所需字体加载完成后显示，加载失败会提示刷新；代码块使用 highlight.js，固定采用官网的 Atom One Dark 配色，与页面明暗模式独立；界面字号默认 14px，可输入 14–20px 并单独重置，与编辑器及阅读字号独立；排版、玻璃透明度、选中文本工具栏均可在设置中调整并即时保存。
|
||
- 选区格式：电脑与触屏选中文字后提供外观、加粗、斜体、下划线、删除线、高亮和链接。外观可设置配色、字体、局部字号与效果；下划线及外观以受限的标准 HTML 行内标签保存在 Markdown 中，源码与导出保留标签，其他软件的显示取决于其 HTML 支持。清除样式只重置局部外观；底部不再显示格式栏。
|
||
- 图片管理：侧栏默认隐藏 `assets` 和 `笔记名.assets`；右键文件夹选择「图片管理」，查看当前目录及直属附件目录的图片，支持检索、排序、网格/列表、批量上传、引用查看及预览、重命名、移动、替换。可切换整个知识库；清理孤立图片须确认候选，服务端再次核对全库引用后移入回收站，可恢复。上传至所选目录的 `assets/`，相同内容自动去重。根目录可在侧栏空白处右键或通过命令面板打开。图片改名/移动会更新笔记中的本地引用；替换保留路径，选择相同扩展名的图片（最大 50 MB），旧图片不进回收站。
|
||
- `--user` 让容器以宿主机用户身份读写数据目录；不指定时容器以 UID 65532 运行，需要该用户对目录有写权限。
|
||
- 请通过 HTTPS 反向代理（Caddy、Nginx 等）访问，并转发 WebSocket（`/api/v1/events`）。
|
||
- 多选与导出：Ctrl/Cmd 点击切换选择，Shift 点击选择可见范围；右键批量删除、移动或导出 Markdown。单篇无附件直接下载 `.md`，其他情况下载包含 Markdown 与本地附件的 ZIP；重名目标不会被覆盖，批量操作会汇报单项失败。
|
||
- 设置：桌面使用居中窗口，手机使用分类与内容两级布局；支持搜索设置并定位、常用排版项单独重置，自动保存状态与失败提示可见。外观、编辑器和日记与模板分别管理，安装入口位于「关于」。
|
||
- 快捷键：支持按命令名称、ID 或组合键搜索，添加、逐条移除和单项/全部重置，并拒绝冲突绑定。默认 Ctrl+Alt+1～6 设置对应级别标题，同级再次触发恢复正文；字号可直接输入。
|
||
- 文件目录操作：右键「文件目录」标题或目录空白处，可搜索、打开标签索引、新建笔记、新建目录、导入文档及管理图片；也可点击标题打开菜单。文件夹右键操作以所选文件夹为目标。
|
||
- 导入：文件目录或文件夹右键菜单选择「导入」，支持多选 UTF-8 `.md` 文件或单个 ZIP（总上传上限 100 MB）。ZIP 新建同名文件夹并保留笔记层级，本地图片归入各笔记同级 `assets/`；全部改链后移除已迁移且无引用的重复原图，其他附件和未使用图片保留。同名不同内容不覆盖，缺失的本地链接会提示，外部图片不会自动下载。
|
||
- 自动化：「API 令牌」中创建只读或读写令牌，以 `Authorization: Bearer <令牌>` 调用 REST API，接口说明见 `/api/v1/openapi.json`。
|
||
|
||
| 环境变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `RAWMARK_DATA` | `/data` | 数据目录（数据库、可重建的搜索索引 `index.db`、默认笔记仓库） |
|
||
| `RAWMARK_VAULT` | `$RAWMARK_DATA/vault` | 笔记仓库目录，可指向已有的笔记文件夹 |
|
||
| `RAWMARK_ADDR` | `:8080` | 监听地址 |
|
||
|
||
文件树默认使用 📂 / 📄，可点击图标或右键“修改图标”，选择表情或内置线性图标。自定义属性存于仓库的 `.rawmark/tree-icons.json`，随应用内移动、重命名及回收站恢复保留，不改动或导出到 Markdown 正文；外部文件操作不保证跟随。
|
||
|
||
## 开发
|
||
|
||
需要 Go 1.27+ 与 Node 24+。开发时不必构建前端或 Docker 镜像，一键启动：
|
||
|
||
```sh
|
||
scripts/dev.sh # 后端 go run -tags dev + 前端 Vite 热更新，Ctrl+C 同时退出
|
||
scripts/dev.sh --host # 前端监听所有网卡，手机访问 http://<电脑 IP>:5173
|
||
```
|
||
|
||
浏览器打开 http://localhost:5173 ，首次使用直接设置登录密码。端口与数据目录可用 `API_PORT`、`WEB_PORT`、`RAWMARK_DATA` 覆盖，详见 `scripts/dev.sh --help`。
|
||
|
||
检查：
|
||
|
||
```sh
|
||
cd web && npm run typecheck && npm test
|
||
go vet -tags dev ./... && go test ./internal/...
|
||
```
|
||
|
||
字体资源已入库，普通构建无需下载或转换。重新生成时，在独立 Python 环境安装 `fonttools[woff]`，下载 [v7.9 指定字体包](https://github.com/subframe7536/maple-font/releases/download/v7.9/MapleMonoNormalNL-NF-CN.zip)，运行 `python3 scripts/prepare-maple-font.py /path/to/MapleMonoNormalNL-NF-CN.zip`；生成 WOFF2 与 `maple-font.css`，保留上游许可。
|