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