AI Knowledge Link（AI知识链接）

把用户的 Word / PDF 文档自动解析为 Markdown、组织成知识库，并为每个知识库生成一个高熵 Secret URL。用户把链接发给任意支持网页访问的 AI，AI 即可按用户描述自主选择并读取文档。

上传文档 → 自动解析 → 转换 Markdown → 建立知识库 → 生成 AI 专属链接
        → 把链接发给任意 AI → AI 读取目录并按描述访问具体文档

状态：MVP 开发完成（Phase 1-14）。完整架构与技术决策见 docs/technical-review.md；需求清单见 docs/requirements.md。

技术栈（MVP v1）

层	技术
后端	Python 3.12+ · FastAPI · SQLAlchemy 2 · Pydantic v2 · Alembic · Jinja2
前端	Vue 3 · TypeScript · Vite · Element Plus · Pinia
存储	SQLite（元数据）+ 本地文件系统（原始文件 + Markdown）
解析	MarkItDown（优先）· PyMuPDF（PDF fallback）· python-docx（DOCX fallback）
搜索	SQLite LIKE（可升级 FTS5）

目录结构

backend/     FastAPI 应用（api 管理端 / public AI公共端 / processors 解析 / retrieval 检索 / storage 存储）
frontend/    Vue 3 管理后台
nginx/       反向代理配置（生产）
data/        SQLite + 用户文件（.gitignore 排除，仅保留 .gitkeep）
docs/        架构与技术文档

快速开始（Windows 开发）

无需 Docker，直接运行。

后端

cd backend
python -m venv .venv
# Git Bash:
source .venv/Scripts/activate
# 或 CMD:
.venv\Scripts\activate

pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

• API 文档：http://localhost:8000/api/docs
• 健康检查：http://localhost:8000/api/health

前端

cd frontend
npm install
npm run dev

• 访问：http://localhost:5173
• Vite 代理：/api 和 /k → localhost:8000

测试

cd backend
python -m pytest tests/ -v

生产部署（Ubuntu + Docker）

1. 安装 Docker

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# 验证
docker --version
docker compose version

2. 克隆项目

sudo mkdir -p /opt/ai-knowledge-link
sudo chown $USER:$USER /opt/ai-knowledge-link
git clone <repo> /opt/ai-knowledge-link
cd /opt/ai-knowledge-link

3. 配置环境

cp .env.example .env

# 编辑 .env，修改以下关键配置：
nano .env

必须修改的配置：

# 生成密钥：python -c "import secrets; print(secrets.token_urlsafe(48))"
SECRET_KEY=<your-secret-key>
ENVIRONMENT=production

4. 创建数据目录

mkdir -p data

5. 启动服务

docker compose up -d --build

6. 验证部署

# 检查容器状态
docker compose ps

# 检查日志
docker compose logs -f

# 健康检查
curl http://localhost/api/healthz

7. 访问

• 前端：http://your-server-ip
• API 文档：http://your-server-ip/api/docs（仅开发环境）
• 公共页面：http://your-server-ip/k/{token}

8. 更新部署

cd /opt/ai-knowledge-link
git pull
docker compose up -d --build

数据不会因为更新丢失（./data/ 是宿主机 volume）。

9. 备份

# 备份 SQLite 数据库
sqlite3 data/app.db ".backup data/backup/app_$(date +%Y%m%d).db"

# 备份用户文件
tar czf data/backup/files_$(date +%Y%m%d).tar.gz data/users/

# 保留最近 7 天备份
find data/backup/ -name "*.db" -mtime +7 -delete
find data/backup/ -name "*.tar.gz" -mtime +7 -delete

10. 恢复

# 恢复数据库
cp data/backup/app_20260901.db data/app.db

# 恢复用户文件
tar xzf data/backup/files_20260901.tar.gz -C /

Nginx 配置（生产）

如果使用独立 Nginx（非 Docker），参考 nginx/nginx.conf：

server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 25M;

    # 前端静态文件
    location / {
        root /opt/ai-knowledge-link/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 60s;
    }

    # 公共 AI 页面代理
    location /k/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        add_header Cache-Control "private, no-cache, no-store" always;
        add_header X-Robots-Tag "noindex, nofollow, noarchive" always;
    }
}

安全须知

• .env 携带全部密钥，绝不提交 Git
• 知识库 Secret URL 即访问凭证（链接即钥匙），请勿公开传播
• 公共 AI 页面不依赖 JS/Cookie/登录；含 noindex meta + robots.txt 屏蔽
• 生产环境必须设置 ENVIRONMENT=production（启用 Cookie Secure、禁用 Swagger）

API 概览

管理端（需登录）

方法	路径	说明
POST	/api/auth/register	注册
POST	/api/auth/login	登录
POST	/api/auth/logout	登出
GET	/api/auth/me	当前用户信息
PATCH	/api/auth/me	修改密码
GET	/api/auth/storage	存储用量
GET	/api/knowledge-bases	知识库列表
POST	/api/knowledge-bases	创建知识库
GET	/api/knowledge-bases/{id}	知识库详情
PUT	/api/knowledge-bases/{id}	编辑知识库
DELETE	/api/knowledge-bases/{id}	删除知识库
POST	/api/knowledge-bases/{id}/regenerate-token	重新生成链接
POST	/api/knowledge-bases/{id}/enable	启用链接
POST	/api/knowledge-bases/{id}/disable	禁用链接
GET	/api/knowledge-bases/{id}/link	获取完整链接
GET	/api/knowledge-bases/{id}/categories	分类列表
POST	/api/knowledge-bases/{id}/categories	创建分类
GET	/api/documents?kb_id=	文档列表
POST	/api/documents/upload	上传文档
GET	/api/documents/{id}	文档详情
PUT	/api/documents/{id}	编辑文档
DELETE	/api/documents/{id}	删除文档
POST	/api/documents/{id}/reprocess	重新解析

公共 AI 端（无需登录）

方法	路径	说明
GET	/k/{token}	知识库首页（HTML）
GET	/k/{token}.md	知识库首页（Markdown）
GET	/k/{token}.txt	知识库首页（纯文本）
GET	/k/{token}.json	知识库首页（JSON）
GET	/k/{token}/search?q=	搜索文档
GET	/k/{token}/doc/{doc_token}	文档页面（HTML）
GET	/k/{token}/doc/{doc_token}.md	文档（Markdown）
GET	/k/{token}/doc/{doc_token}.txt	文档（纯文本）

文档

• 技术审查报告 — 架构、ER、API、安全模型、风险清单、6 个扩展接口
• 需求清单 — 完整需求与完成状态