pbeke/qownnotes-api

QOwnNotes Web API 镜像文档

概述

QOwnNotes Web API 镜像提供了 QOwnNotes 笔记应用的 Web API 服务，允许通过 HTTP 接口与 QOwnNotes 笔记数据进行交互。该镜像封装了轻量级 API 服务，可直接访问 QOwnNotes 的笔记数据库，支持标准的笔记管理操作，适用于开发者将 QOwnNotes 集成到自动化流程、第三方应用或自定义工作流中。

核心功能与特性

• 完整的笔记操作支持：提供 RESTful API 接口，支持笔记的创建（Create）、读取（Read）、更新（Update）、删除（Delete）等核心操作。
• 数据同步兼容：与 QOwnNotes 原生数据格式无缝对接，确保 API 操作与桌面客户端操作的数据一致性。
• 安全访问控制：支持通过 API 密钥（API Key）进行身份验证，防止未授权访问。
• 轻量级部署：基于精简基础镜像构建，资源占用低，可快速启动和扩展。
• 日志监控：提供详细的请求日志，支持日志级别配置（如 info、debug），便于问题排查。

使用场景

• 自动化笔记管理：通过脚本或工具调用 API 实现定时备份、标签整理、过期笔记清理等自动化任务。
• 第三方应用集成：将 QOwnNotes 笔记数据集成到自定义应用（如个人仪表盘、知识管理系统）中。
• 跨平台数据访问：通过 Web 接口在移动设备或其他平台访问 QOwnNotes 笔记，无需直接安装客户端。
• 工作流联动：与自动化工具（如 Node-RED、IFTTT）联动，实现基于笔记事件的触发式操作（如新增笔记时自动同步到云盘）。

使用方法与配置说明

基本部署（docker run）

通过以下命令快速启动 QOwnNotes Web API 服务：

bash
docker run -d \
  --name qownnotes-web-api \
  -p 3000:3000 \
  -v /path/to/qownnotes/data:/app/data \
  -e API_KEY="your_secure_api_key" \
  -e LOG_LEVEL="info" \
  docker.xuanyuan.run/qownnotes-web-api:latest

参数说明：

• -p 3000:3000：映射容器内 API 服务端口（默认 3000）到主机端口。
• -v /path/to/qownnotes/data:/app/data：挂载 QOwnNotes 数据目录（需替换为实际路径，通常位于用户目录下的 .config/QOwnNotes 或 QOwnNotes 文件夹）。
• -e API_KEY：设置访问 API 所需的密钥（建议使用强随机字符串），未设置时将禁用身份验证（不推荐生产环境）。
• -e LOG_LEVEL：日志级别，可选值：debug、info、warn、error，默认 info。

Docker Compose 配置

创建 docker-compose.yml 文件进行更灵活的部署管理：

yaml
version: '3'
services:
  qownnotes-web-api:
    image: docker.xuanyuan.run/qownnotes-web-api:latest
    container_name: qownnotes-web-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /path/to/qownnotes/data:/app/data:ro  # 建议设为只读（ro）以增强安全性
    environment:
      - API_KEY="your_secure_api_key"
      - LOG_LEVEL="info"
      - PORT=3000  # 容器内服务端口，默认为 3000，如需修改需同步调整端口映射

启动服务：

bash
docker-compose up -d

环境变量说明

API 端点示例

以下为常用 API 端点示例（假设服务运行在 http://localhost:3000，且已设置 API_KEY=your_secure_api_key）：

获取所有笔记

• 请求：GET http://localhost:3000/api/notes
• 请求头：Authorization: Bearer your_secure_api_key
• 响应：返回所有笔记的列表（JSON 格式），包含笔记 ID、标题、内容、创建时间、标签等信息。

创建新笔记

• 请求：POST http://localhost:3000/api/notes
• 请求头：Authorization: Bearer your_secure_api_key、Content-Type: application/json
• 请求体：

  json
  {
    "title": "API 创建的测试笔记",
    "content": "这是通过 QOwnNotes Web API 创建的笔记内容。",
    "tags": ["api", "test"]
  }
  

• 响应：返回创建的笔记详情（JSON 格式），包含自动生成的笔记 ID。

更新笔记

• 请求：PUT http://localhost:3000/api/notes/{noteId}（{noteId} 替换为目标笔记 ID）
• 请求头：Authorization: Bearer your_secure_api_key、Content-Type: application/json
• 请求体：

  json
  {
    "title": "更新后的笔记标题",
    "content": "更新后的笔记内容。"
  }
  

• 响应：返回更新后的笔记详情。

删除笔记

• 请求：DELETE http://localhost:3000/api/notes/{noteId}（{noteId} 替换为目标笔记 ID）
• 请求头：Authorization: Bearer your_secure_api_key
• 响应：成功时返回 204 No Content。

注意事项

• 数据目录权限：确保挂载的 QOwnNotes 数据目录具有容器可读取的权限（推荐设置为只读，避免 API 误操作影响客户端数据）。
• API 密钥安全：生产环境中必须设置强 API_KEY，并避免在客户端代码或公开网络中暴露。
• 版本兼容性：请确保镜像版本与 QOwnNotes 客户端版本兼容，以避免数据格式不匹配问题。