企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• RAG
• 后端
• 前端

本文基于 OpenChat（LLMs custom-chatbots console）仓库中的开发清单 dj_backend_server/docs/todo.md，结合 Django 后端（dj_backend_server）的真实源码，梳理 PDF 数据源、Website 数据源、聊天前端与 Docker 部署四大模块中「已完成」与「待办」的功能全貌。读完你将掌握：PDF 从上传、哈希去重、OCR 清洗到向量库入库的完整链路，网站递归爬虫的过滤与进度机制，以及向量库联动删除、Resync、细粒度状态机等仍未落地的规划方向，从而准确理解该系统当前的能力边界与下一步演进重点。

1. 文档定位：一份反映系统能力地图的开发清单

todo.md不是传统意义上的安装教程或 API 手册，而是一份带完成标记的功能规划清单。它按功能域划分为四个板块：

• PDF：PDF 数据源的上传、解析、状态管理、错误处理与向量库联动；
• WEBSITE：网站数据源的递归爬虫、Resync、数据一致性；
• CHAT：聊天控件的前端体验与本地化；
• SERVER - DOCKER：部署层的 SSL 与数据持久化。

每条目要么标注(done 日期)表示已落地，要么保持无标记表示仍是待办。从源码结构看，这份清单与该仓库 Django 后端（dj_backend_server/）的代码演进高度对应，例如pdf_handler.py、crawler.py中的注释与实现细节均能一一印证清单条目，因此它本质上就是系统当前「能力地图 + 技术债清单」。下文按板块逐条对照源码解读。

2. PDF 数据源：已完成的能力与尚未落地的规划

2.1 上传 → 摄取 → 入库的完整链路

todo.md 的 PDF 板块全部围绕一条核心链路展开。结合源码，该链路完整为：

1. 上传：[views_pdf_data_source.py](https://link.gitcode.com/i/338d3692cb6e252407ece75833dd0679)接收request.FILES.getlist('pdffiles')，为每个文件计算 MD5 哈希，再由HandlePdfDataSource（handle_pdf_datasource.py）写入website_data_sources/<folder_name>/目录，其中folder_name是secrets.token_hex(20)随机值，每个文件以uuid4() + 扩展名重命名存储。
2. 触发信号：上传成功后发送pdf_data_source_added信号（pdf_datasource_was_added.py），由监听器 ingest_pdf_data_source.py 组装请求体并 POST 到APP_URL + "/api/ingest/"。
3. 异步任务分发：views_ingest.py 收到type=pdf后调用pdf_handler_task.delay(...)，通过 Celery（tasks.py）进入异步执行。
4. 解析与入库：pdf_handler.py 的txt_to_vectordb使用DirectoryLoader加载 PDF（内部解析器）或 TXT（外部 OCR 模式），经RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)切分后，由init_vector_store（init_vector_store.py）写入 Pinecone 或 Qdrant，namespace即 Chatbot 的 ID。

注意：爬虫爬到的 PDF 内容文件同样存放在website_data_sources/目录下，这正是 todo.md 中「website 解析过程中发现 PDF/DOC 推送到 PDF Handler」条目的物理基础。

2.2 已落地：哈希去重、OCR 与 LLM 文本清理

todo.md 中三条 PDF 待办已标记完成（日期均为 31.10.2023），源码可逐一验证：

• 同名同哈希跳过上传：views_pdf_data_source.py在写入前会遍历该 Chatbot 名下所有PdfDataSource的files_info，若hash与original_name均一致则跳过（打印File with hash ... already exists），避免重复摄取。
• OCR + LLM 纠错：pdf_handler.py 的process_pdf在PDF_LIBRARY=external时调用 OCRWebService REST 接口提取文本，并写入同名.txt文件；若OCR_LLM=1，则通过process_text_with_llm（make_chain.py）将 OCR 文本交由 LLM 修正语法拼写、剔除无意义内容后再落盘。相关环境变量（OCR_LICCODE、OCR_USERNAME、OCR_LANGUAGE、OCR_LLM）均可在 example.env.docker 中配置。
• 删除按钮与确认弹窗：todo 标记 REMOVED 的「Resync on PDF」被弃用，同时落地了「Delete」按钮：[views_chatbot.py](https://link.gitcode.com/i/e6f06987fda6ef572525e36fcf01ada3)的delete_file调用PdfDataSource.delete_files()（pdf_data_sources.py）删除物理文件并尝试删除目录，随后删除数据库记录并带成功消息重定向。

2.3 已落地：错误与警告入库

todo.md（PDF 与 WEBSITE 板块各一条，标记 28.10.2023）要求「Capture errors and warnings and log them into the database」。源码中该机制贯穿所有处理环节：pdf_handler、txt_to_vectordb、process_pdf、website_handler、get_llm等函数在异常路径都会写入FailedJob记录（failed_jobs.py），字段包含uuid、connection、queue、payload、exception与failed_at，使后台任务失败可被审计与排查。

2.4 待办：细粒度上传状态机

todo 规划了"Uploaded"、"Parsed"、"Successful"、"Failed"四态。当前实现的粒度仍较粗：

状态枚举定义见 ingest_status_enum.py，前端settings-data页面（views_chatbot_settings.py）仅渲染 PENDING / SUCCESS / FAILED 三种徽章，Uploaded/Parsed等中间态与错误明细展示仍待实现。

2.5 待办：向量数据库的联动删除与数据审查

todo 中「Delete 按钮也删除向量库数据」和「从向量库检索/审查数据」目前均未落地：

• delete_file视图中明确留有注释Remove the record from the vector database / You need to implement this part based on your vector database；
• PdfDataSource.delete_files()中的delete_from_vectordb(self.chatbot_id)调用同样被注释掉；
• 「同名但哈希不同时先删旧向量数据再重启任务」也未实现：当前逻辑下新文件会以新 UUID 文件名写入，旧向量数据不会被清除，长期看可能形成向量库中的冗余分片。

这些是数据生命周期治理方向的核心待办，实现时需要在init_vector_store同层新增按namespace（即 Chatbot ID）删除向量的能力。

3. 网站数据源：爬虫现状与规划

3.1 递归爬虫与二进制过滤（已落地）

todo.md 中「爬虫不爬二进制文件/URL」「调查 PNG 等二进制文件被解析」两条已于 28-29.10.2023 标记完成。对应实现位于 crawler.py：

• crawl()维护crawled_urls去重，达到MAX_PAGES_CRAWL（默认 15，见 example.env.docker）即停止；
• 显式过滤.png .jpg .jpeg .gif .bmp .ico .tif .tiff .webp等二进制扩展名；
• extract_links()使用 BeautifulSoup 提取<a>标签，规范化 URL（去掉 query/fragment），并只保留与根 URL 同域（scheme+netloc）的链接；
• 进度计算通过calculate_crawling_progress(len(crawled_urls), max_pages)写入website_data_sources.crawling_progress，状态机由 website_data_source_status_enum.py 定义：pending / in_progress / completed / failed。

爬虫结束后，监听器 ingest_website_data_source.py 会请求/api/ingest/，由 website_handler.py 读取爬取文本并写入向量库，同时将crawling_status置为completed。

3.2 页面标题提取（源码已实现）

todo 中的「Title of the crawled URL is not read」虽未标记 done，但源码中已实现对应逻辑：get_crawled_page_title()（crawler.py）解析<title>标签，store_crawled_page_content_to_database()将其写入CrawledPages.title字段（模型见 crawled_pages.py）。从源码结构可以推断该条目已实质完成，todo 只是未同步更新标记。

3.3 待办：Resync / Smart Resync 与 PDF 发现

WEBSITE 板块中未标记完成的三条规划：

• Website Resync：重新触发某个已建站点的全量爬取与向量重建；
• Smart Resync：智能增量同步（仅重爬变更内容）；
• 解析中发现 PDF/DOC 时推送到 PDF Handler：crawl()目前对非二进制 HTML 之外的内容不做分支处理，虽然website_handler的DirectoryLoader使用glob="**/*.txt"，爬取内容以 TXT 落盘，但 PDF/DOC 的识别与转交 PDF 摄取链路（含复选框开关）尚不存在。

实现 Resync 时，可复用现有信号与 ingest 链路：爬虫完成信号 →/api/ingest/→ Celery 任务，只需补充「对已完成站点允许重新发起」的入口与状态复位逻辑。

3.4 待办：数据一致性与管理体验

• 删除 Chatbot 未清理关联表：delete_bot（views_chatbot_settings.py）仅执行bot.delete()，而WebsiteDataSource、PdfDataSource、CrawledPages、ChatbotSetting、ChatHistory等表（见 web/models 目录下各模型）会留下孤儿数据；
• WEB 与 DATA 列表分页：data_settings目前直接filter(...).order_by('-id')全量返回，未做分页；
• 爬虫中断与恢复：「sync occasionally stops」的调查与重启机制尚未实现——crawler.py对网络异常采用pass静默跳过，状态仅在顶层异常时置为failed。

3.5 待办：LLM 设置进入 Dashboard

todo 规划将 Temperature、OpenAI key、OpenAI Model 等 LLM 参数纳入 Dashboard 可视化配置。当前这些配置仍停留在环境变量层：OPENAI_API_TYPE、OPENAI_API_MODEL、OPENAI_API_TEMPERATURE（OpenAI 侧，见 get_openai_llm.py），以及 Azure 系列变量与本地 llama2（get_llama_llm）。ChatbotSetting表（chatbot_settings.py）虽已提供name/value键值存储，但尚未用于 LLM 参数。

4. 聊天与前端：移动端与本地化

CHAT 板块仅剩一条待办：移动端友好（Mobile friendly）。其余均已落地：

• 本地化 chat.js 与 search.js（done 31.10.2023）：通过环境变量LNG_BOT、LNG_ERROR、LNG_WRITE、LNG_ASK（example.env.docker 末尾）在构建/运行时替换前端英文文案；
• 用真实 URL 替换 JS 内 localhost（done 29.10.2023）：get_chat_view（views_chatbot.py）将APP_URL注入chat.html模板供前端使用；不过后端send_message调用 LLM 服务时仍硬编码http://localhost:3000/api/chat，分布式部署时需关注该点。

5. 服务器与 Docker：SSL 与数据持久化（已落地）

SERVER - DOCKER 板块两条均在 10 月下旬完成：

• NGINX + SSL（done 26.10.2023）：模板 nginx/nginx.template.conf 定义了 80 端口 HTTP 与 443 端口 HTTPS 两个 server 块，server_name ${APP_URL}通过模板变量注入；SSL 证书路径为/etc/nginx/ssl/cert.pem与privkey.pem，启用TLSv1.2 TLSv1.3、HSTS、OCSP stapling，并将/代理到web:8000；
• website_data_sources 外部卷（done 24.10.2023）：docker-compose.yaml 中web与celery_worker服务均挂载./website_data_sources:/app/website_data_sources，使爬取与上传的文件目录独立于容器层，便于挂载大容量存储并在重启后保留数据。同文件还编排了mysql、qdrant、redis、adminer、nginx等基础设施。

6. 待核查数据表清单

todo.md 列出若干需要核查的表。结合 dj_backend_server/web/models 目录与迁移文件（dj_backend_server/web/migrations）逐一对照：

从迁移历史可以推断：web_pdfdatasourceerrorlog已被废弃删除，错误日志统一收敛到failed_jobs；text_data_sources等遗留模型是否保留，正是 todo 中「Check this tables」要回答的问题。

7. 结语：如何借助这份清单理解与部署 OpenChat

todo.md的价值在于它精确刻画了 OpenChat 数据源体系「已完成 vs 未完成」的边界：

• 可开箱即用：PDF 上传去重、OCR/LLM 文本清洗、网站递归爬虫（含二进制过滤与进度）、错误入库、NGINX SSL、外部数据卷持久化均已就绪，部署配置可参考 example.env.docker 与 docker-compose.yaml；
• 值得优先补强：向量库联动删除（PDF 删除/哈希变更场景）、细粒度摄取状态机、Website Resync/Smart Resync、PDF 发现转交、删除 Chatbot 的级联清理、列表分页与爬虫断点恢复；
• 架构约束提示：向量库目前由STORE环境变量在 Pinecone/Qdrant 间切换（init_vector_store.py），LLM 由OPENAI_API_TYPE在 azure/openai/llama2 间切换（get_openai_llm.py），任何新增的「向量删除」「审查」能力都应在这两个抽象层上实现，以保持多后端兼容。

如果你正计划基于 OpenChat 二次开发，建议以本文第二节的 PDF 链路和第三节的爬虫链路为起点阅读源码，再对照清单逐条评估：凡是标记(done)的条目可直接信任，凡是未标记的条目就是系统的已知能力缺口——它们既是风险点，也是功能迭代的候选清单。

• 人工智能
• 大模型
• AI 应用
• RAG
• 后端
• 前端