WuKong 项目实战：从零构建 AI 驱动的网页分享平台

项目概述

WuKong（悟空）是一个基于 FastAPI 的轻量级网页分享平台，核心功能是让用户上传 HTML/Markdown/图片等文件，AI 自动转换并预览，一键生成限时分享链接。项目部署在 namehonor.com/wukoong/，服务器为 115.159.xxx（宝塔面板 + Python 3.7）。

技术栈

后端：FastAPI + SQLite + Uvicorn

前端：原生 HTML/CSS/JS（单页应用）

AI 集成：Agnes API（多模态模型），用于文件 OCR 识别和图片内容提取

部署：Nginx 反向代理 → Uvicorn 监听 8765 端口

数据库：SQLite（files 表存储 slug、content、mime_type 等字段）

核心功能开发历程

1. 文件上传与 AI 转换

最初版本仅支持 HTML 和 Markdown 文件的直接上传预览。后续迭代中逐步扩展了文件格式支持：

文档类：PDF、DOCX、XLSX、PPTX、TXT — 通过本地库（PyPDF2、python-docx、openpyxl）提取文本后发送给 Agnes AI 转换为 Markdown 或 HTML 表格

图片类：JPG、PNG、GIF、BMP、WEBP — 转为 base64 后通过 Agnes 多模态接口进行 OCR 识别，文字转 Markdown，表格转 HTML `

`关键代码路径：`/api/files/ai-convert` 端点处理所有 AI 转换请求，根据文件扩展名选择不同 Prompt：PDF/DOCX/TXT → `AI_CONVERT_SYSTEM_PROMPT`（转 Markdown）XLSX → `AI_EXCEL_TO_HTML_PROMPT`（转 HTML 表格）图片 → `AI_IMAGE_OCR_PROMPT`（文字转 MD，表格转 HTML）2. 预览渲染机制前端通过 iframe srcdoc 隔离渲染 HTML 内容，Markdown 内容则通过内置的 renderMarkdown() 函数转换为带样式的 HTML。对于 Excel 转换后的 HTML 表格，同样使用 iframe 展示，确保表格样式完整保留。3. 发布与分享预览确认无误后，点击”发布”按钮将内容 POST 到 `/api/files`，系统生成唯一 slug 并存储到 SQLite。用户可通过 `/view/{slug}` 或短链 `/v/{slug}` 访问分享页面。支持密码保护和过期时间设置。4. 管理面板独立的管理后台（admin.html）提供文件列表查询、搜索、排序、状态筛选等功能，管理员可查看所有分享记录并进行删除操作。遇到的挑战与解决方案挑战一：浏览器缓存导致旧版 JS 接管上传流程**问题**：修改了 app.js 后，浏览器仍加载旧版缓存，导致新逻辑不生效。**解决**：在 index.html 中给 script 标签添加版本号参数 `?v=10-image-support`，强制浏览器重新下载最新 JS 文件。挑战二：发布按钮静默失败 — null 引用异常**问题**：点击”发布”按钮无任何反应，浏览器控制台报错 `Cannot set properties of null (setting ‘href’)`。**根因**：服务器部署的 index.html 预览区被意外截断，缺失 `titleInput` 等 DOM 元素，但 JS 中的 `publishFromPreview()` 仍强引用这些 ID，导致 TypeError 中断整个发布流程。**解决**：在 `showResult()` 函数中增加可选链防御 `?.value`，对可能为 null 的 DOM 元素做空值检查；同时修复服务器端 index.html 的截断问题，确保预览区包含完整的发布表单结构。挑战三：API Key 无效导致 504 Gateway Timeout**问题**：AI 转换请求超时，网关层返回 504。**根因**：旧版 API Key 已失效，httpx 客户端等待超时。**解决**：更新 `.env` 和 `server.py` 中的 API Key，验证连通性后重启 Uvicorn 服务。挑战四：Excel 文件 MIME 类型处理**问题**：用户上传 xlsx 文件后，预览显示为纯文本而非格式化表格。**解决**：前后端协同修改——后端 server.py 对 xlsx 使用专门的 `AI_EXCEL_TO_HTML_PROMPT` 返回 HTML “ 结构；前端 app.js 根据 `ext === ‘xlsx’` 判断设置 `mimeType = ‘text/html’`；预览渲染时检测到 text/html 使用 iframe srcdoc 展示，确保表格样式正确。项目架构│ Nginx (反向代理) ││ 转发 /wukoong/* → 127.0.0.1:8765 │└──────────────────┬──────────────────────────┘│┌──────────────────▼──────────────────────────┐│ Uvicorn (FastAPI) ││ ││ ┌─────────────┐ ┌─────────────────────┐ ││ │ GET / │ │ POST /api/files │ ││ │ index.html │ │ 发布内容 → SQLite │ ││ └─────────────┘ └─────────────────────┘ ││ │ ││ ┌─────────────────────┐ ┌─────────────┐ ││ │ POST /api/files │ │ GET /view/ │ ││ │ /ai-convert │ │ {slug} │ ││ └─────────────────────┘ └─────────────┘ ││ ││ ┌─────────────────────┐ ┌─────────────┐ ││ │ Agnes API │ │ SQLite DB │ ││ │ (OCR / 转换) │ │ (files 表) │ ││ └─────────────────────┘ └─────────────┘ │└─────────────────────────────────────────────┘版本迭代记录V1：基础 HTML/Markdown 上传预览 + 发布V2：添加 PDF/DOCX/XLSX 等文档类型 AI 转换V3：修复发布按钮 null 引用异常，完善预览区 DOMV3.1：新增图片格式支持（JPG/PNG/GIF/BMP/WEBP），实现图片 OCR 识别，文字转 Markdown，表格转 HTML经验总结1. **前端防御性编程至关重要**：DOM 元素可能因部署问题缺失，必须用可选链 `?.` 和空值检查保护关键逻辑2. **浏览器缓存是隐形杀手**：静态资源更新务必加版本号参数强制刷新3. **前后端 MIME 类型必须对齐**：文件转换后的 mimeType 设置、预览渲染方式、发布存储格式三者需保持一致4. **API Key 定期验证**：依赖外部 AI 服务的功能需做好超时处理和 Key 有效性检查5. **最小化修改原则**：用户明确要求”不添加额外输入框”时，应通过纯 JS 逻辑兼容而非修改 HTML 结构