InkSight Docker

基于 Docker 的 InkSight 墨水屏桌面伴侣本地部署方案。

项目简介

InkSight (墨鱼) 是一个智能 e-ink 桌面伴侣系统，使用 ESP32-C3 设备在 4.2 寸墨水屏上显示 LLM 生成的内容。

本仓库提供完整的 Docker 部署方案，包含：

• Backend: Python FastAPI 后端（内容生成、渲染、缓存）
• Webapp: Next.js 15 网页应用

快速开始

前置要求

• Docker & Docker Compose
• Git

1. 克隆或下载本仓库

# 如果通过 git 克隆
git clone https://github.com/insdram/inksight-docker.git
cd inksight-docker

# 或者解压后进入目录
cd inksight-docker

2. 配置环境变量

复制环境变量模板并编辑：

cp .env.example .env
# 编辑 .env 填入你的 API keys

至少需要填写一个 LLM API Key：

服务	环境变量	申请地址
DeepSeek (推荐)	DEEPSEEK_API_KEY	https://platform.deepseek.com/
阿里云通义	DASHSCOPE_API_KEY	https://dashscope.console.aliyun.com/
Moonshot	MOONSHOT_API_KEY	https://platform.moonshot.cn/

3. 启动服务

docker compose up -d

4. 访问服务

服务	地址
Web 应用	http://localhost:3000
Backend API	http://localhost:8080
配置页面	http://localhost:8080/config.html
预览页面	http://localhost:8080/preview
编辑器	http://localhost:8080/editor
仪表盘	http://localhost:8080/dashboard

目录结构

inksight-docker/
├── docker-compose.yml     # Docker 服务编排
├── .env.example            # 环境变量模板
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── api/               # FastAPI 路由
│   ├── core/              # 核心模块
│   │   ├── modes/         # 模式定义 (builtin/custom)
│   │   ├── json_content.py
│   │   ├── json_renderer.py
│   │   └── ...
│   ├── webconfig/         # 静态配置页面
│   └── fonts/             # 字体文件
├── webapp/
│   ├── Dockerfile
│   ├── package.json
│   ├── src/
│   └── ...
└── docs/                  # 可选：项目文档

自定义模式开发

InkSight 支持通过 JSON 定义自定义模式。

创建自定义模式

1. 在 backend/core/modes/custom/ 目录创建 JSON 文件
2. 或通过编辑器页面 (http://localhost:8080/editor) 在线创建

最小示例

{
  "mode_id": "MY_MODE",
  "display_name": "我的模式",
  "cacheable": true,
  "content": {
    "type": "llm",
    "prompt_template": "生成一条有趣的语录。{context}",
    "fallback": { "text": "暂无内容" }
  },
  "layout": {
    "body": [
      {
        "type": "centered_text",
        "field": "text",
        "font": "noto_serif_light",
        "font_size": 18
      }
    ]
  }
}

外部数据模式

{
  "mode_id": "MY_BIBI",
  "display_name": "我的Bibi",
  "content": {
    "type": "external_data",
    "url": "https://api.example.com/data",
    "fallback": { "items": [] }
  },
  "layout": {
    "body": [
      {
        "type": "text",
        "field": "items.0.content",
        "font": "noto_serif_light",
        "font_size": 16
      }
    ]
  }
}

环境变量

变量名	必填	说明
DEEPSEEK_API_KEY	是*	DeepSeek API Key
DASHSCOPE_API_KEY	是*	阿里云 DashScope API Key
MOONSHOT_API_KEY	是*	Moonshot API Key
INKSIGHT_ALLOWED_HOSTS	否	允许的 Host，逗号分隔，默认 *
INKSIGHT_CORS_ALLOW_LAN	否	是否允许 LAN 访问，默认 1

*至少需要填写一个 API Key

常用命令

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f backend
docker compose logs -f webapp

# 重启服务
docker compose restart backend

# 重新构建（代码修改后）
docker compose up -d --build

# 停止服务
docker compose down

自定义端口

编辑 docker-compose.yml 中的端口映射：

services:
  backend:
    ports:
      - "8080:8080"  # 修改左侧数字改变主机端口
  webapp:
    ports:
      - "3000:3000"  # 修改左侧数字改变主机端口

开发相关

本地开发（非 Docker）

Backend:

cd backend
pip install -r requirements.txt
python scripts/setup_fonts.py
cp .env.example .env
# 编辑 .env 填入 API keys
uvicorn api.index:app --reload --port 8080

Webapp:

cd webapp
npm install
npm run dev

运行测试

cd backend
pytest

项目文档

• 设备配置指南
• 自定义模式开发
• API 文档
• 常见问题 FAQ

License

MIT License