HTTP API 使用指南

1. 开始使用

1. 解锁 LockMemo，等待首次同步完成。在 Memos 中添加一个 Secret，设置 Key = demo.api-key、文本 Value 为 example-value。Key 在当前保险库的所有 Secret 中必须唯一，区分大小写。
2. 打开 Settings → Sync → HTTP API。复制 Access token，然后点击 Start access。
3. 首次启动后，打开右上角 ⋮ → Client configuration，点击 Export public CA，把证书保存为下载目录中的 lockmemo-local-ca.pem。如果使用其他路径，请修改下方范例。
4. 在同一台 Mac 的终端运行下方命令。下面先用 pbpaste 读取刚复制的 Token，不需要把 Token 直接写进命令历史。

LOCKMEMO_CA="$HOME/Downloads/lockmemo-local-ca.pem"
LOCKMEMO_TOKEN="$(pbpaste)"

这里是 HTTPS，需要信任 App 导出的本机 CA。范例使用 --cacert 校验证书，无需把 CA 安装到系统信任列表，也不要用 -k 跳过校验。

2. cURL 范例

检查服务状态

curl --noproxy '*' --http1.1 --silent --show-error --fail \
  --cacert "$LOCKMEMO_CA" \
  https://127.0.0.1:49443/v1/status

{"service":"lockmemo","apiVersion":1,"state":"active"}

此接口不需要 Token，也不会返回 Secret。服务停止后通常无法连接，而不是返回状态 JSON。

读取文本

printf 'Authorization: Bearer %s\n' "$LOCKMEMO_TOKEN" |
  curl --noproxy '*' --http1.1 --silent --show-error --fail \
    --cacert "$LOCKMEMO_CA" \
    --header @- \
    --header 'Content-Type: application/json' \
    --data-binary '{"key":"demo.api-key"}' \
    https://127.0.0.1:49443/v1/resolve

成功响应是 example-value 的原始 UTF-8 字节，没有 JSON 包装，也不会额外添加换行。--header @- 从标准输入读取 Authorization 头。

读取文件

在 Secret 中再添加 demo.config，点击回形针选择一个测试 JSON 文件。下面命令会写入或覆盖当前目录的 demo-config.json；请使用专门的测试目录。

umask 077
printf 'Authorization: Bearer %s\n' "$LOCKMEMO_TOKEN" |
  curl --noproxy '*' --http1.1 --silent --show-error --fail \
    --cacert "$LOCKMEMO_CA" \
    --header @- \
    --header 'Content-Type: application/json' \
    --data-binary '{"key":"demo.config"}' \
    --output ./demo-config.json \
    https://127.0.0.1:49443/v1/resolve

文本和文件使用同一个接口。文件返回原始内容，不是文件名或 Base64；输出文件名由客户端决定。测试完成后清理当前 shell 中的 Token 变量：

unset LOCKMEMO_TOKEN

3. Python 范例

安装 Python 3 后可直接运行以下脚本，无需第三方库。按提示输入或粘贴 Token，输入不会回显。成功内容写到标准输出，也可替换为你自己的业务处理。

import getpass
import json
from pathlib import Path
import ssl
import sys
import urllib.error
import urllib.request

ca_file = Path.home() / "Downloads" / "lockmemo-local-ca.pem"
context = ssl.create_default_context(cafile=str(ca_file))
token = getpass.getpass("LockMemo access token: ")
request = urllib.request.Request(
    "https://127.0.0.1:49443/v1/resolve",
    data=json.dumps({"key": "demo.api-key"}).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    method="POST",
)
# Keep loopback requests direct, even when a proxy is configured.
opener = urllib.request.build_opener(
    urllib.request.ProxyHandler({}),
    urllib.request.HTTPSHandler(context=context),
)
try:
    with opener.open(request, timeout=30) as response:
        sys.stdout.buffer.write(response.read())
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8')}", file=sys.stderr)
    raise SystemExit(1)
except urllib.error.URLError:
    print("Check LockMemo access, the local CA file, and the endpoint.", file=sys.stderr)
    raise SystemExit(1)

4. 接口约定

• 请求头为 Authorization: Bearer <token> 和 Content-Type: application/json。请求体只能包含一个 key 字段，不传 Memo 标题。
• 成功响应为 application/octet-stream；只返回 Value，不返回 Key、Notes、Memo 标题或附件元数据。没有条目列表、批量导出或写入接口。
• 请求体最多 4 KiB，单个 Value 最多 10 MiB。认证通过的读取请求最多每分钟 60 次；排队和连接也有限制。
• 仅监听本机 IPv4 回环地址，使用 HTTP/1.1，不接受 chunked 请求或浏览器 Origin。请在本机脚本调用，不从网页 JavaScript、其他电脑或手机访问。

5. Token 与启停

• 开启时可读取当前保险库的全部 Secret，包括后来新增的条目；普通 Memo、Vault 凭据和 Codes 不在读取范围内。持有 Token 的本机程序可在服务开启时读取这些 Secret。
• Token 为 43 字符的安全随机值，仅本机保存，不进入保险库的 Git 同步。启停、重新解锁和重启 App 都不会更换；只有点击“更新”并确认后才会更换已有 Token。
• 更新 Token 会停止服务，旧 Token 立即失效。更新脚本中的 Token 后，手动重新启动 API。轮换本机 CA 后，还需要重新导出 CA 并更新脚本使用的证书文件。
• 服务没有运行倒计时；手动停止、锁定保险库、休眠、退出或 Premium 失效时停止。重新解锁后需要手动开启。
• 访问日志入口在设置页，日志只保存在本机，保留最近 7 天内最多 500 条。不要把 Token 或 Secret 值写入代码仓库或构建日志。

6. 常见问题

无法连接：先确认 App 已启动、已解锁，HTTP API 显示运行中，且端口 49443 没有被其他程序占用。锁定、写入暂停或连接限制也可能直接关闭连接，而不返回 JSON 错误。证书错误：使用此 Mac 当前导出的 CA，保留 HTTPS 校验。