1. 从零搭建一个OpenResearch：我为什么选择自建研究管理平台

第一次听到“OpenResearch”这个词，很多人会以为又是一个学术搜索引擎或者论文聚合站。但真正做过研究、带过团队、或者长期跟踪某个领域进展的人会明白，市面上缺的从来不是“搜论文”的工具，而是一个能把研究过程本身管起来的东西。OpenResearch这个项目标题，核心指向的就是这样一类系统：它不生产知识，它管理知识的生产过程。

我最初接触这个方向，是因为自己手头同时跟了三个课题，每个课题都有文献、实验记录、数据文件、会议纪要、待验证的假设、失败的尝试。这些东西散落在文件夹、笔记软件、聊天记录和脑子里，三个月后回头看，连自己当时为什么放弃某条路线都想不起来。这不是记忆力问题，是研究过程缺乏结构化载体的问题。OpenResearch要解决的，就是这个。

它适合谁？我认为有三类人值得认真看：一是独立研究者或小团队负责人，需要低成本维护自己的研究资产；二是企业里的研发小组，需要把探索性工作和工程化工作分开管理；三是任何需要长期跟踪一个复杂问题的人，比如写综述的学生、做竞品分析的产品经理。你不需要是程序员，但如果你愿意花一个下午理解它的组织逻辑，后面省下的时间是以月为单位计算的。

这篇文章我会按实际搭建和使用的顺序来讲，从整体设计思路到具体落地，再到踩过的坑。所有代码和配置都是可复现的，参数选择我会说明理由，你根据自己的场景调整即可。

2. 整体设计思路：为什么不是“又一个笔记软件”

2.1 研究管理的核心矛盾：自由度和可检索性

笔记软件的问题在于太自由。你可以建无数个文件夹，用任何标签，写任何格式。三个月后，你面对的是一个只有当时的自己才能看懂的迷宫。而项目管理软件的问题在于太死板，它假设你的工作流是线性的、可预测的，但研究恰恰是高度非线性的——你今天验证的假设，可能推翻上周的结论，也可能开启一个全新的分支。

OpenResearch的设计思路，我理解下来是在这两者之间找平衡：用结构化的容器承载非结构化的内容。具体来说，它把研究拆成几个固定层级——项目、课题、条目、附件——但每个层级内部的内容格式完全自由。你可以把一条实验记录写成一段话，也可以附上原始数据、代码、截图、外部链接。结构只负责“东西放在哪”，不负责“东西长什么样”。

这个选择背后的逻辑很实在：检索和回顾时，你首先需要知道“去哪个项目找”，这是结构解决的问题；找到之后，你需要看到完整的上下文，这是自由格式解决的问题。两者缺一不可。

2.2 技术选型：为什么用轻量级方案而不是重型平台

市面上有现成的研究管理平台，功能很全，但我最终选择自建，原因有三个。第一，数据主权。研究过程中的中间数据、失败记录、未发表的思路，放在别人的服务器上，心理上始终有个疙瘩。第二，定制成本。现成平台的功能80%你用不上，但缺的那20%恰好是你最需要的，改又改不动。第三，长期可维护性。一个轻量级自建系统，只要技术栈选得保守，五年后还能跑；一个依赖特定厂商的重型平台，三年后可能连登录入口都变了。

我的技术选型如下：

注意：如果你预期数据量在十万条条目以内，SQLite完全够用。我实测过五万条记录加全文索引，查询响应在毫秒级。不要过早引入Elasticsearch这类重型组件，维护成本远大于收益。

2.3 数据模型：四个核心实体就够了

OpenResearch的数据模型我反复简化过，最终只保留四个核心实体：

• Project（项目）：最高层级，对应一个研究方向或一个资助周期。字段包括名称、描述、状态、创建时间。
• Topic（课题）：项目下的分支，对应一个具体问题或子方向。一个项目可以有多个课题，课题之间可以有依赖关系。
• Entry（条目）：课题下的最小记录单元。一条实验记录、一篇文献笔记、一个想法、一次会议纪要，都是Entry。Entry有类型字段区分，但存储结构统一。
• Attachment（附件）：挂在Entry上的文件，可以是数据、代码、图片、PDF。

这个模型的好处是极简。你不需要为每种内容类型建一张表，也不需要处理复杂的关联关系。Entry的类型字段用枚举值区分，查询时按类型过滤即可。我试过更复杂的模型，比如把文献、实验、想法分成独立实体，结果就是关联查询写起来很痛苦，而且很多内容天然跨类型，硬分类反而别扭。

3. 核心细节解析：每个字段都是踩坑后加的

3.1 Entry的状态机设计

Entry有一个状态字段，取值是：draft、active、verified、archived、rejected。这个设计来自一个教训：早期版本没有状态，所有条目平铺，三个月后我分不清哪些是已验证的结论，哪些是随手记的猜测。

状态流转规则如下：

• 新建Entry默认draft，表示还没整理。
• 整理后改为active，表示正在跟进。
• 如果这条记录被后续实验或文献证实，改为verified。
• 如果被证伪或放弃，改为rejected，但不删除。
• 长期不跟进但仍有参考价值的，改为archived。

关键点：rejected状态必须保留。研究中最有价值的信息往往不是“什么对了”，而是“什么错了以及为什么错”。我踩过的坑是早期删除了失败记录，结果半年后重新踩了同一个坑。

3.2 全文搜索的索引策略

SQLite的FTS5模块支持全文索引，但默认的分词器对中文支持一般。我的做法是：

CREATE VIRTUAL TABLE entry_fts USING fts5( title, content, tokenize='unicode61' );

unicode61分词器对中文按字符切分，虽然不如专门的中文分词精准，但胜在零依赖、零配置。实测下来，对于研究记录这种以关键词检索为主的场景，够用了。如果你对中文搜索要求高，可以引入jieba分词预处理，把分词结果存到一个额外字段再建索引。

搜索查询示例：

def search_entries(query: str, limit: int = 20): sql = """ SELECT e.id, e.title, e.entry_type, e.status, snippet(entry_fts, 1, '<mark>', '</mark>', '...', 32) as snippet FROM entry_fts JOIN entry e ON e.id = entry_fts.rowid WHERE entry_fts MATCH ? ORDER BY rank LIMIT ? """ return db.execute(sql, (query, limit)).fetchall()

snippet函数会返回匹配片段并高亮关键词，这对快速判断条目相关性非常有用。

3.3 附件管理的两个原则

附件管理我定了两个原则，都是血泪教训换来的。

原则一：附件永不覆盖，只追加。每次修改数据文件，生成新版本，旧版本保留。文件名带时间戳或版本号。这样你永远可以回溯到任何一个历史状态。我试过覆盖式保存，结果一次误操作把关键数据覆盖了，找不回来。

原则二：附件路径存相对路径，不存绝对路径。数据库里只存相对于项目根目录的路径，比如attachments/2024/exp_001_v2.csv。这样整个项目目录可以整体迁移、打包、备份，不会因为换电脑或换目录结构导致链接失效。

目录结构建议：

openresearch_data/ ├── db.sqlite3 ├── attachments/ │ ├── 2024/ │ │ ├── exp_001_v1.csv │ │ └── exp_001_v2.csv │ └── 2025/ └── exports/

4. 实操过程：从零到可用的完整步骤

4.1 环境准备与依赖安装

我假设你用的是Linux或macOS，Windows用户建议用WSL。Python版本3.10以上。

mkdir openresearch && cd openresearch python -m venv venv source venv/bin/activate # Windows用 venv\Scripts\activate pip install fastapi uvicorn jinja2 python-multipart aiofiles

依赖说明：FastAPI做Web框架，uvicorn做ASGI服务器，jinja2做模板渲染，python-multipart处理文件上传，aiofiles做异步文件写入。没有引入ORM，直接用sqlite3标准库，减少依赖。

4.2 数据库初始化脚本

import sqlite3 from pathlib import Path DB_PATH = Path("openresearch_data/db.sqlite3") DB_PATH.parent.mkdir(parents=True, exist_ok=True) def init_db(): conn = sqlite3.connect(DB_PATH) c = conn.cursor() c.execute(""" CREATE TABLE IF NOT EXISTS project ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, description TEXT DEFAULT '', status TEXT DEFAULT 'active', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) """) c.execute(""" CREATE TABLE IF NOT EXISTS topic ( id INTEGER PRIMARY KEY AUTOINCREMENT, project_id INTEGER NOT NULL, name TEXT NOT NULL, description TEXT DEFAULT '', parent_topic_id INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (project_id) REFERENCES project(id) ) """) c.execute(""" CREATE TABLE IF NOT EXISTS entry ( id INTEGER PRIMARY KEY AUTOINCREMENT, topic_id INTEGER NOT NULL, title TEXT NOT NULL, content TEXT DEFAULT '', entry_type TEXT DEFAULT 'note', status TEXT DEFAULT 'draft', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (topic_id) REFERENCES topic(id) ) """) c.execute(""" CREATE TABLE IF NOT EXISTS attachment ( id INTEGER PRIMARY KEY AUTOINCREMENT, entry_id INTEGER NOT NULL, file_path TEXT NOT NULL, original_name TEXT, file_size INTEGER, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (entry_id) REFERENCES entry(id) ) """) c.execute(""" CREATE VIRTUAL TABLE IF NOT EXISTS entry_fts USING fts5( title, content, tokenize='unicode61' ) """) conn.commit() conn.close() if __name__ == "__main__": init_db() print("Database initialized.")

运行这个脚本后，你会得到一个空的数据库文件。注意entry_fts是虚拟表，需要手动同步数据，后面会讲同步逻辑。

4.3 核心API实现

FastAPI的路由我按实体分组，每个实体一组CRUD。这里展示Entry的创建和搜索，其他类似。

from fastapi import FastAPI, Form, UploadFile, File, HTTPException from fastapi.responses import HTMLResponse, RedirectResponse from fastapi.templating import Jinja2Templates from fastapi import Request import sqlite3 import shutil from pathlib import Path from datetime import datetime app = FastAPI() templates = Jinja2Templates(directory="templates") DB_PATH = Path("openresearch_data/db.sqlite3") ATTACH_DIR = Path("openresearch_data/attachments") def get_db(): conn = sqlite3.connect(DB_PATH) conn.row_factory = sqlite3.Row return conn @app.post("/entry/create") async def create_entry( topic_id: int = Form(...), title: str = Form(...), content: str = Form(""), entry_type: str = Form("note"), ): conn = get_db() c = conn.cursor() c.execute( "INSERT INTO entry (topic_id, title, content, entry_type) VALUES (?, ?, ?, ?)", (topic_id, title, content, entry_type) ) entry_id = c.lastrowid # 同步全文索引 c.execute( "INSERT INTO entry_fts (rowid, title, content) VALUES (?, ?, ?)", (entry_id, title, content) ) conn.commit() conn.close() return RedirectResponse(f"/entry/{entry_id}", status_code=303) @app.get("/search") async def search(q: str = "", request: Request = None): if not q: return templates.TemplateResponse("search.html", {"request": request, "results": []}) conn = get_db() c = conn.cursor() c.execute(""" SELECT e.id, e.title, e.entry_type, e.status, snippet(entry_fts, 1, '<mark>', '</mark>', '...', 32) as snippet FROM entry_fts JOIN entry e ON e.id = entry_fts.rowid WHERE entry_fts MATCH ? ORDER BY rank LIMIT 50 """, (q,)) results = c.fetchall() conn.close() return templates.TemplateResponse("search.html", {"request": request, "results": results, "query": q})

注意：FTS5的MATCH语法对特殊字符敏感，用户输入如果包含*、"、(等，需要转义或预处理。我的做法是简单过滤，只保留字母、数字、中文和空格。更严谨的做法是用参数化查询配合转义函数。

4.4 附件上传与版本管理

附件上传的关键是生成不冲突的文件名，并记录原始文件名。

@app.post("/entry/{entry_id}/attach") async def upload_attachment(entry_id: int, file: UploadFile = File(...)): conn = get_db() c = conn.cursor() c.execute("SELECT id FROM entry WHERE id = ?", (entry_id,)) if not c.fetchone(): conn.close() raise HTTPException(404, "Entry not found") # 按年月分目录 now = datetime.now() subdir = ATTACH_DIR / str(now.year) / f"{now.month:02d}" subdir.mkdir(parents=True, exist_ok=True) # 生成唯一文件名 timestamp = now.strftime("%Y%m%d_%H%M%S") safe_name = file.filename.replace(" ", "_") stored_name = f"{timestamp}_{safe_name}" file_path = subdir / stored_name # 写入文件 with open(file_path, "wb") as f: shutil.copyfileobj(file.file, f) # 记录相对路径 rel_path = str(file_path.relative_to(ATTACH_DIR.parent)) file_size = file_path.stat().st_size c.execute( "INSERT INTO attachment (entry_id, file_path, original_name, file_size) VALUES (?, ?, ?, ?)", (entry_id, rel_path, file.filename, file_size) ) conn.commit() conn.close() return RedirectResponse(f"/entry/{entry_id}", status_code=303)

这个实现里，文件名带时间戳，天然支持版本管理。同一份数据修改后重新上传，会生成新文件，旧文件保留。你可以在Entry页面按时间倒序列出所有附件，一眼看到最新版本。

4.5 数据导出与备份

研究数据最怕丢。我设置了一个定时任务，每天凌晨打包整个openresearch_data目录，保留最近30天的备份。

#!/bin/bash # backup.sh BACKUP_DIR="/path/to/backups" DATA_DIR="/path/to/openresearch_data" DATE=$(date +%Y%m%d) tar -czf "$BACKUP_DIR/openresearch_$DATE.tar.gz" -C "$(dirname $DATA_DIR)" "$(dirname $DATA_DIR)/$(basename $DATA_DIR)" # 删除30天前的备份 find "$BACKUP_DIR" -name "openresearch_*.tar.gz" -mtime +30 -delete

配合crontab：

0 2 * * * /path/to/backup.sh

提示：备份文件建议再同步一份到外部存储或另一台机器。我试过只存本地，结果硬盘故障时备份和原始数据一起没了。现在我用rsync同步到一台旧笔记本上，成本几乎为零。

5. 常见问题与排查技巧实录

5.1 全文索引不同步怎么办

这是最常见的问题。表现是：新建或修改Entry后，搜索不到。原因是entry_fts是独立虚拟表，不会自动跟随entry表更新。

解决方案有两种。一是像上面代码那样，在每次写操作后手动同步。二是用触发器自动同步：

CREATE TRIGGER entry_ai AFTER INSERT ON entry BEGIN INSERT INTO entry_fts (rowid, title, content) VALUES (new.id, new.title, new.content); END; CREATE TRIGGER entry_au AFTER UPDATE ON entry BEGIN UPDATE entry_fts SET title = new.title, content = new.content WHERE rowid = new.id; END; CREATE TRIGGER entry_ad AFTER DELETE ON entry BEGIN DELETE FROM entry_fts WHERE rowid = old.id; END;

触发器方案更省心，但调试时如果出问题不容易发现。我的建议是初期用手动同步，逻辑清晰可控；稳定后再加触发器。

5.2 中文搜索效果差怎么优化

unicode61分词器对中文是按单字切分，搜索“实验数据”会匹配包含“实”、“验”、“数”、“据”任意一个字的条目，召回率高但精准度低。

优化方案是引入jieba分词，在写入时把分词结果存到一个content_tokenized字段，FTS索引这个字段。

import jieba def tokenize(text: str) -> str: return " ".join(jieba.cut_for_search(text))

然后建索引时用tokenize='unicode61'，但写入的是空格分隔的词。搜索时同样对查询词分词。实测精准度提升明显，代价是写入时多一步处理，以及jieba的依赖。

5.3 数据库锁死怎么处理

SQLite默认的锁机制在并发写入时会报database is locked。研究管理场景下并发不高，但如果你同时开了多个浏览器标签页操作，可能遇到。

解决方案：连接时设置超时和WAL模式。

conn = sqlite3.connect(DB_PATH, timeout=10) conn.execute("PRAGMA journal_mode=WAL")

WAL模式允许读写并发，超时设置让写操作等待而不是立即失败。这两个设置加上后，我基本没再遇到锁死问题。

5.4 常见问题速查表

5.5 几个我踩过的坑

坑一：Entry内容用Markdown存，但渲染时没做XSS过滤。研究记录里贴了一段HTML代码，结果页面渲染时把整个布局搞乱了。后来加了转义，只允许白名单标签。

坑二：Topic层级设计成无限嵌套，结果自己都记不清哪个Topic在哪一层。后来限制最多三层：项目-课题-子课题。超过三层说明你的分类粒度太细了，应该用标签而不是层级。

坑三：早期没加updated_at字段，改过的条目和新建的条目分不清。加上之后，按更新时间排序，最近在跟进的课题一目了然。

坑四：附件文件名直接用原始名，结果两个不同Entry上传了同名文件，后一个覆盖了前一个。现在文件名强制带时间戳前缀，彻底杜绝冲突。

6. 后续扩展方向与个人体会

这套系统我用了大半年，数据量到了两万多条Entry，搜索和浏览依然流畅。后续我打算加两个功能：一是Entry之间的关联关系，比如“这条记录推翻了那条结论”，用简单的双向链接实现；二是定期回顾提醒，对active状态超过30天没更新的Entry发通知，避免课题烂尾。

如果你也想搭一套，我的建议是先从最小可用版本开始，不要一上来就追求功能完整。核心就是四个实体加全文搜索，先把数据管起来，用起来，再根据实际痛点迭代。我见过太多人花两周搭了一个功能齐全的系统，结果用三天就放弃了，因为录入成本太高。OpenResearch的价值在于持续使用，而不是功能多寡。

最后分享一个录入技巧：我给自己定了一个规矩，任何实验或阅读结束后，五分钟内必须录入一条Entry，哪怕只有一句话。这五分钟的投入，换来的是三个月后还能准确回忆起当时的思路。研究中最贵的不是设备，是时间，而时间最怕的就是遗忘。