拓冰网站定制 
文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载WaLiOffice 是一款一句话生成 PPT / Word / Excel / Markdown / 图表 / 视频的 Web 端 AI Agent 智能办公平台输入自然语言即可产出办公文件并全流程流式反馈。本文聚焦该项目的代码落地第一步——工程初始化与项目结构你将完整掌握 Rust 后端axum tokio的目录划分与模块职责、Cargo.toml 依赖组织方式、.env环境变量配置与tracing日志初始化以及基于rust-embed的前端独立开发、后端统一打包策略为后续 LLM 客户端、数据库、工具系统与 ReAct 循环的学习打好地基。一、为什么第一步是搭工程架子而不是写 AI 代码一个从 0 到 1 的 AI Agent 项目最容易犯的错误是一上来就写 AI 调用代码。但正如本节课程强调的AI 代码写起来其实不复杂复杂的是架构清晰、模块解耦、方便扩展。原因很朴素——如果写了一个月的 AI 代码最后发现所有逻辑都揉在一个文件里改一行 bug 可能引发十个新 bug。这恰恰是架构师的价值所在在动笔写业务代码之前先把目录结构、模块划分、依赖管理、日志初始化这些工程地基搞明白。所以本节的核心任务是为 WaLiOffice 搭建脚手架——Rust 后端工程初始化。先把智能体的基础开发与各类办公软件对接的骨架立起来之后再扩展 DSH 插件版DeepSeek Harness Agent 引擎就有了清晰的落点。整个项目的前置输入是前两节的内容需求分析明确了对话即生产的产品形态见 第1-1节WaLiOffice需求分析技术栈选型与架构设计确定了 Rust React AI Agent 的组合方案见 第1-2节技术栈选型与系统架构设计。二、本章诉求你将从这一节收获什么本节课程明确列出了 5 个学习目标这也是读者读完本节后应具备的能力了解 WaLiOffice 项目的整体目录结构知道每个目录是干什么的——这是阅读任何中大型项目的第一步能力掌握 Rust 后端工程的依赖配置Cargo.toml——理解 axum、tokio、sqlx、rust-embed 等核心依赖在工程中各自承担的角色理解 Axum Web 框架的路由组织方式——routes/mod.rs如何聚合子模块、构建统一 Router学会用rust-embed把前端资源打包进后端二进制——实现单一可执行文件、零外部依赖的部署形态掌握.env环境变量配置和tracing日志初始化——配置与可观测性是工程可运维的前提。这 5 点诉求覆盖了一个 Web 后端工程初始化最重要的五个维度结构、依赖、路由、打包、配置与日志。三、工程整体设计前端独立开发、后端统一打包WaLiOffice 采用前端独立开发、后端统一打包的策略这是整个工程最重要的一条设计主线开发期前端代码放在frontend/目录独立运行于 Vite Dev Server实现热更新、快速迭代生产期后端通过rust-embed把前端的编译产物dist直接编译打包进后端二进制部署时只需要一个可执行文件零外部依赖。这条策略直接决定了后文的目录结构形态——前后端代码在同一个仓库中共存但边界清晰server/是主战场frontend/是独立子工程二者只在构建期耦合。从系统架构层面看见 walioffice.md 的架构图说明整个系统是用户 → 前端 → 后端核心 → 数据的清晰流向React 18 单页应用负责流式对话与产物预览Rust (axum) 后端承载 Agent ReAct 循环引擎与纯 Rust 文档渲染引擎SQLite 作为嵌入式数据库零运维存储会话与产物右侧独立对接 LLM API、图片生成、视频生成、搜索服务等外部能力。这一切最终都被打包进一个 Rust 二进制正是本节脚手架要落实的形态。四、WaLiOffice 项目目录结构全解析本节课程给出了完整的工程目录树这是阅读整个项目的地图逐层展开如下WaLiOffice/ ├── server/ ← Rust 后端主战场 │ ├── src/ │ │ ├── main.rs ← 程序入口模块声明 启动流程 │ │ ├── config.rs ← 配置管理.env 解析OnceLock 全局单例 │ │ ├── state.rs ← 全局状态DB Pool / LLM Client │ │ ├── error.rs ← 统一错误处理AppError AppResult │ │ ├── routes/ ← HTTP 路由层mod.rs 构建路由 各子模块 │ │ ├── agent/ ← AI Agent 核心ReAct 循环 / 工具注册 / 意图识别 │ │ ├── llm/ ← LLM 客户端HTTP 调用 / 流式 SSE / 类型定义 │ │ ├── db/ ← 数据库层AnyPool 6 个 repo 模块 │ │ ├── models/ ← 数据模型请求/响应 DTO │ │ ├── render/ ← 文档渲染DOCX / XLSX / PPTX │ │ ├── file_extract.rs ← 附件解析PDF / Office / CSV / JSON │ │ ├── image_ocr.rs ← 图片 OCR 识别 │ │ └── auth/ ← JWT 认证中间件 │ ├── Cargo.toml ← Rust 依赖配置 │ └── Cargo.lock ├── migrations/ ← SQL 迁移脚本SQLite MySQL ├── frontend/ ← React TypeScript 前端 │ ├── src/ │ │ ├── api/ ← Axios HTTP 客户端 │ │ ├── components/ ← UI 组件ChatPanel / SlidePreview / ArtifactPanel / ... │ │ ├── pages/ ← 页面Studio.tsx 主界面 │ │ ├── stores/ ← Zustand 状态管理 │ │ ├── types/ ← TypeScript 类型定义 │ │ ├── config/ ← 前端配置 │ │ ├── lib/ ← 工具函数库 │ │ └── styles/ ← 全局样式 │ └── package.json └── docs/ ← 文档4.1 server/ —— Rust 后端主战场server/是 WaLiOffice 的绝对核心采用高内聚、低耦合的模块划分方式组织每个目录单一职责main.rs程序入口负责模块声明与启动流程是整个二进制的起点config.rs配置管理解析.env环境变量通过OnceLock实现全局单例保证配置只被读取一次、全局共享state.rs全局状态持有数据库连接池DB Pool与 LLM 客户端LLM Client通过 axum 的 State 提取器注入各路由处理器error.rs统一错误处理定义AppError错误枚举与AppResult类型别名让全链路错误收敛到统一的转换与响应格式routes/HTTP 路由层mod.rs负责构建整个路由表各子模块按业务域拆分例如 Chat 路由与 SSE 流式端点详见 第2-7节后端Chat路由与SSE端点agent/AI Agent 核心承载 ReAct 循环推理 → 行动 → 观察、工具注册表与意图识别是大脑所在详见 第2-5节ReAct循环核心实现 与 第2-4节工具Trait定义与注册表机制llm/LLM 客户端封装 HTTP 调用、流式 SSE 解析与类型定义分为非流式LlmClient与流式LlmStreamClient两条调用链路详见 第2-2节LLM客户端与流式SSE实现db/数据库层基于AnyPool统一 SQLite / MySQL 双数据库连接池内含 6 个 repo 模块每个 repo 对应一组表操作详见 第2-3节数据库设计与会话持久化models/数据模型定义请求 / 响应 DTO隔离 HTTP 层与领域层的数据形态render/文档渲染纯 Rust 渲染 DOCX / XLSX / PPTX 三大办公产物不依赖任何外部服务或命令行工具file_extract.rs附件解析解析用户上传的 PDF、Office 文档、CSV、JSON 附件为附件理解类工具提供内容输入image_ocr.rs图片 OCR对上传图片做文字识别支撑图生图、图文理解等场景auth/认证实现 JWT 认证中间件配合 bcrypt 密码哈希保护用户体系详见 第4-3节用户认证与JWT。这一层模块划分与后端的职责边界一一对应路由层只做 HTTP 编排Agent 层只做智能体决策LLM 层只做模型通信渲染层只做文档产出——每个模块都可以独立替换、独立测试。4.2 migrations/ —— SQL 迁移脚本migrations/存放 SQL 迁移脚本同时覆盖SQLite 与 MySQL两套方言。这背后的设计考量是SQLite 适合本地开发与个人用户零配置、零运维MySQL 适合多用户团队与云端部署并发能力强、运维生态成熟两者各有适用场景因此工程同时维护两套迁移脚本。数据库层的统一访问由sqlx的AnyPool连接池抽象完成上层代码无需感知底层是哪种数据库。4.3 frontend/ —— React TypeScript 前端前端是一个标准的 React 18 TypeScript Vite SPA 工程按api / components / pages / stores / types / config / lib / styles组织代码同样是单一职责的模块化思想api/基于 Axios 封装 HTTP 客户端统一管理请求与错误处理components/UI 组件库包含ChatPanel对话面板、SlidePreview幻灯片预览、ArtifactPanel产物面板等核心组件以及 ECharts 图表、Draw.io 图表、图片 / 视频播放器等产物渲染器pages/页面层其中Studio.tsx是主界面——三栏式工作台左侧会话列表与文件管理中间对话区与附件上传右侧产物预览stores/基于 Zustand 的轻量状态管理适用于会话、流式消息、产物等中等复杂度的前端状态types/TypeScript 类型定义与后端 DTO 对齐保证前后端契约一致config/前端运行配置如 API 地址、上传限制等lib/工具函数库如 SSE 流式解析、图片压缩上传等styles/全局样式配合 TailwindCSS 与 Radix UI 无头组件体系构建高质量 UI。前端与后端通过SSE 流式协议实时通信前端通过fetch ReadableStream解析message / artifact_update / state_update / tool_result / done / project_update等事件类型用户能实时看到 Agent 的思考、工具调用与产物生成过程详见 第2-8节前端对话界面与流式渲染。4.4 docs/ —— 文档docs/存放项目的课程文档与架构说明即读者正在阅读的本系列教程与源码仓库同仓维护做到文档跟着代码走。五、Rust 后端依赖配置Cargo.tomlCargo.toml 是 Rust 工程的项目说明书。结合工程模块划分与各章节文档WaLiOffice 的依赖大致覆盖以下类别各自承担明确的职责依赖类别代表 crate承担职责Web 框架与异步运行时axum、tokio构建异步 Web 服务、路由与并发处理HTTP 客户端reqwestLLM 客户端发起 HTTP 调用文本、图片、视频 API序列化serde、serde_jsonDTO 序列化、工具参数 schema、JSON 产物处理环境变量dotenvy类解析.env配置文件日志tracing、tracing-subscriber结构化日志收集与输出数据库sqlxAnyPoolSQLite MySQL 双数据库统一连接池认证jsonwebtoken、bcryptJWT 签发 / 校验与密码哈希文档渲染docx-rs、rust_xlsxwriter纯 Rust 生成 DOCX / XLSX 文件静态资源嵌入rust-embed前端dist编译期嵌入后端二进制附件与多媒体PDF / Office 解析、图片 OCR、ffmpeg 调用相关依赖支撑file_extract.rs、image_ocr.rs与视频本地兜底注意以上依赖的具体版本号以仓库Cargo.lock锁定的版本为准工程应通过 Cargo.lock 保证构建的可复现性。其中文档渲染的选型动机在 第1-2节 中有明确论述——采用纯 Rust 渲染而不是 Java 的 EasyExcel 或 Python 的 python-docx正是为了不引入额外的外部服务或命令行依赖让渲染发生在同一个进程内零网络开销、零额外故障点。六、程序入口 main.rs模块声明与启动流程main.rs是整个二进制的起点承担模块声明 启动流程两件事模块声明将config、state、error、routes、agent、llm、db、models、render、auth等模块统一在 crate 根声明形成全局可见的模块树启动流程从启动链路看大致顺序为——解析.env环境变量并初始化全局配置OnceLock→ 建立数据库连接池与 LLM 客户端并组装进全局状态AppState→ 注册全部 Agent 工具对应register_all_tools启动流程见 第2-4节→ 构建 axum 路由表 → 绑定端口启动 HTTP 服务 → 通过tracing输出监听日志。启动流程遵循先配置、后状态、再路由的依赖顺序任何一步失败都会在启动期暴露而不是在运行期抛错——这是 Rust 后端工程的一个良好实践。七、config.rs.env 解析与 OnceLock 全局单例配置管理模块解决配置从哪来、如何安全共享的问题来源.env环境变量文件本地开发与部署时通过修改环境变量即可调整行为无需改代码全局单例使用OnceLockRust 标准库提供的一次性初始化容器持有全局配置对象保证配置在整个进程生命周期内只解析一次任何线程读取到的都是同一份不可变配置天然线程安全配置覆盖面从系统架构文档支持多 LLM 端点分离配置文本 / 图片 / 视频独立 API的描述可以推断.env至少会覆盖以下类别——服务监听端口、数据库连接地址、JWT 密钥、文本 LLM 端点API Key / Base URL / 模型名、图片生成 API 端点、视频生成 API 端点等。多组端点分离是为了让不同任务对话、生图、出视频各走各的模型通道互不干扰详见 第4-1节配置管理与多组LLM端点。八、state.rs全局状态共享 DB Pool 与 LLM Clientstate.rs定义AppState全局状态结构持有两类核心资源DB Pool数据库连接池AnyPool所有路由处理器通过它访问 SQLite / MySQL避免每次请求新建连接LLM Client非流式LlmClient与流式LlmStreamClient实例供 ReAct 循环与 SSE 推送使用见 第2-2节。在 axum 中AppState通过State提取器注入路由处理器实现全局共享、只读持有、按需取用是连接配置层与业务层的关键枢纽。九、error.rsAppError 与 AppResult 统一错误处理error.rs定义了AppError统一错误枚举覆盖数据库错误、LLM 调用错误、工具执行错误、参数解析错误、认证错误等各类失败场景AppResultResultT, AppError的类型别名让所有模块的函数签名统一。它的价值在于无论错误发生在哪一层最终都能转换为一致的 HTTP 响应返回给前端同时保留足够的上下文用于tracing日志排查。这是中大型后端工程的基础设施避免每个模块各自为战地抛错误。十、routes/Axum 路由组织方式路由层采用mod.rs聚合 子模块拆分的组织方式routes/mod.rs负责把各子模块的路由组装成完整的 axumRouter统一挂载中间件如 JWT 认证中间件与状态注入各子模块按业务域划分例如 Chat 路由含 SSE 流式端点、认证路由、文件管理路由等每个子模块只关心自己负责的路径段。这种组织方式与目录结构一一呼应新增一个业务域就是新增一个 routes 子模块 在 mod.rs 挂一行路由符合开闭原则也方便按域做单元测试。十一、rust-embed把前端资源打包进后端二进制rust-embed是本节的核心知识点它实现前端独立开发、后端统一打包策略的关键机制编译期嵌入后端构建时rust-embed通过 derive 宏将frontend/构建产出的dist目录静态资源HTML / JS / CSS / 图片等直接嵌入二进制文件运行时静态服务axum 通过 fallback 机制托管这些嵌入资源访问根路径即返回前端页面访问/assets/...即返回静态文件单一二进制最终部署产物只有一个可执行文件包含完整的后端逻辑与前端资源零外部依赖不需要在服务器上安装 Node、拷贝前端目录或配置静态文件服务器。与 Docker 多阶段构建配合node:20构建前端 →rust:1.80编译后端 →debian:bookworm-slim作为运行镜像见 第5-1节Docker多阶段构建这条单一二进制部署链路把运维成本压到了最低——复制一个文件即可完成部署这也是个人与中小企业本地化部署 AI 办公平台非常友好的形态。十二、tracing日志初始化tracing是 Rust 生态的结构化日志与追踪框架在本工程中的初始化要点在main.rs启动早期初始化全局tracing_subscriber设置日志输出格式与级别过滤器通常通过RUST_LOG环境变量控制日志级别之后各模块通过tracing宏info!/warn!/error!/debug!输出带模块路径、字段上下文的日志相比简单的 printlntracing支持结构化字段与 Span 追踪能把一次 HTTP 请求或一轮 Agent 循环的关键步骤串联起来为排查LLM 调用为什么超时工具执行到哪一步失败了这类问题提供依据。结合error.rs的统一错误类型日志与错误处理形成闭环错误产生时记录结构化日志前端收到统一错误响应运维在日志中定位根因。十三、这一节为后续章节打下的地基工程初始化不是终点而是后续所有功能的载体。以本节脚手架为基础WaLiOffice 课程后续逐步填肉智能体对话基础第 2 部分LLM 客户端与流式 SSE第2-2节→ 数据库与会话持久化第2-3节→ 工具 Trait 与注册表第2-4节→ ReAct 循环第2-5节→ 意图识别第2-6节→ Chat 路由与 SSE 端点第2-7节→ 前端对话界面第2-8节工具集成第 3 部分在agent/工具注册表之上注册 Markdown、Word、PPT、Excel、ECharts 图表、Draw.io、图像、视频、联网搜索等 10 个业务工具底层渲染复用render/模块增强设计第 4 部分多组 LLM 端点配置第4-1节、附件处理第4-2节、JWT 认证第4-3节部署与 DevOps第 5 部分Docker 多阶段构建与云服务器部署配置第5-1节 / 第5-2节。可以说本节搭建的server/分层agent / llm / db / render / routes / auth与frontend/分层pages / components / stores / api / types就是整个 WaLiOffice 的钢筋骨架后续每一节新增的能力都能在骨架中找到自己的落点这正是一个从 0 到 1 的 AI Agent 项目最值得先想清楚的部分。赞分享文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载相关推荐Sunshine 实战指南从安装到跑通6步走完核心串流链路Sunshine 实战指南从安装到跑通6步走完核心串流链路 Sunshine 是一款自托管游戏串流服务器配合 Moonlight 客户端让你用手机、电视音视频后端Vencord脚手架工具与项目初始化Vencord脚手架工具与项目初始化 引言为什么需要专业的脚手架工具 还在为Discord客户端修改项目的复杂配置而头疼吗还在手动搭建开发环境、处理依赖冲即时通讯桌面应用前端插件系统Tauri 开发速查手册初始化脚手架、调试手段、安卓打包与配置结构全解析jaywcjlove/reference 备忘清单精讲Tauri 开发速查手册初始化脚手架、调试手段、安卓打包与配置结构全解析jaywcjlove/reference 备忘清单精讲 本篇技术指南以 jaywc文档知识库教程开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WaLiOffice 工程初始化与项目结构：Rust + Axum 后端脚手架搭建与单一二进制打包全解析
文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载WaLiOffice 是一款一句话生成 PPT / Word / Excel / Markdown / 图表 / 视频的 Web 端 AI Agent 智能办公平台输入自然语言即可产出办公文件并全流程流式反馈。本文聚焦该项目的代码落地第一步——工程初始化与项目结构你将完整掌握 Rust 后端axum tokio的目录划分与模块职责、Cargo.toml 依赖组织方式、.env环境变量配置与tracing日志初始化以及基于rust-embed的前端独立开发、后端统一打包策略为后续 LLM 客户端、数据库、工具系统与 ReAct 循环的学习打好地基。一、为什么第一步是搭工程架子而不是写 AI 代码一个从 0 到 1 的 AI Agent 项目最容易犯的错误是一上来就写 AI 调用代码。但正如本节课程强调的AI 代码写起来其实不复杂复杂的是架构清晰、模块解耦、方便扩展。原因很朴素——如果写了一个月的 AI 代码最后发现所有逻辑都揉在一个文件里改一行 bug 可能引发十个新 bug。这恰恰是架构师的价值所在在动笔写业务代码之前先把目录结构、模块划分、依赖管理、日志初始化这些工程地基搞明白。所以本节的核心任务是为 WaLiOffice 搭建脚手架——Rust 后端工程初始化。先把智能体的基础开发与各类办公软件对接的骨架立起来之后再扩展 DSH 插件版DeepSeek Harness Agent 引擎就有了清晰的落点。整个项目的前置输入是前两节的内容需求分析明确了对话即生产的产品形态见 第1-1节WaLiOffice需求分析技术栈选型与架构设计确定了 Rust React AI Agent 的组合方案见 第1-2节技术栈选型与系统架构设计。二、本章诉求你将从这一节收获什么本节课程明确列出了 5 个学习目标这也是读者读完本节后应具备的能力了解 WaLiOffice 项目的整体目录结构知道每个目录是干什么的——这是阅读任何中大型项目的第一步能力掌握 Rust 后端工程的依赖配置Cargo.toml——理解 axum、tokio、sqlx、rust-embed 等核心依赖在工程中各自承担的角色理解 Axum Web 框架的路由组织方式——routes/mod.rs如何聚合子模块、构建统一 Router学会用rust-embed把前端资源打包进后端二进制——实现单一可执行文件、零外部依赖的部署形态掌握.env环境变量配置和tracing日志初始化——配置与可观测性是工程可运维的前提。这 5 点诉求覆盖了一个 Web 后端工程初始化最重要的五个维度结构、依赖、路由、打包、配置与日志。三、工程整体设计前端独立开发、后端统一打包WaLiOffice 采用前端独立开发、后端统一打包的策略这是整个工程最重要的一条设计主线开发期前端代码放在frontend/目录独立运行于 Vite Dev Server实现热更新、快速迭代生产期后端通过rust-embed把前端的编译产物dist直接编译打包进后端二进制部署时只需要一个可执行文件零外部依赖。这条策略直接决定了后文的目录结构形态——前后端代码在同一个仓库中共存但边界清晰server/是主战场frontend/是独立子工程二者只在构建期耦合。从系统架构层面看见 walioffice.md 的架构图说明整个系统是用户 → 前端 → 后端核心 → 数据的清晰流向React 18 单页应用负责流式对话与产物预览Rust (axum) 后端承载 Agent ReAct 循环引擎与纯 Rust 文档渲染引擎SQLite 作为嵌入式数据库零运维存储会话与产物右侧独立对接 LLM API、图片生成、视频生成、搜索服务等外部能力。这一切最终都被打包进一个 Rust 二进制正是本节脚手架要落实的形态。四、WaLiOffice 项目目录结构全解析本节课程给出了完整的工程目录树这是阅读整个项目的地图逐层展开如下WaLiOffice/ ├── server/ ← Rust 后端主战场 │ ├── src/ │ │ ├── main.rs ← 程序入口模块声明 启动流程 │ │ ├── config.rs ← 配置管理.env 解析OnceLock 全局单例 │ │ ├── state.rs ← 全局状态DB Pool / LLM Client │ │ ├── error.rs ← 统一错误处理AppError AppResult │ │ ├── routes/ ← HTTP 路由层mod.rs 构建路由 各子模块 │ │ ├── agent/ ← AI Agent 核心ReAct 循环 / 工具注册 / 意图识别 │ │ ├── llm/ ← LLM 客户端HTTP 调用 / 流式 SSE / 类型定义 │ │ ├── db/ ← 数据库层AnyPool 6 个 repo 模块 │ │ ├── models/ ← 数据模型请求/响应 DTO │ │ ├── render/ ← 文档渲染DOCX / XLSX / PPTX │ │ ├── file_extract.rs ← 附件解析PDF / Office / CSV / JSON │ │ ├── image_ocr.rs ← 图片 OCR 识别 │ │ └── auth/ ← JWT 认证中间件 │ ├── Cargo.toml ← Rust 依赖配置 │ └── Cargo.lock ├── migrations/ ← SQL 迁移脚本SQLite MySQL ├── frontend/ ← React TypeScript 前端 │ ├── src/ │ │ ├── api/ ← Axios HTTP 客户端 │ │ ├── components/ ← UI 组件ChatPanel / SlidePreview / ArtifactPanel / ... │ │ ├── pages/ ← 页面Studio.tsx 主界面 │ │ ├── stores/ ← Zustand 状态管理 │ │ ├── types/ ← TypeScript 类型定义 │ │ ├── config/ ← 前端配置 │ │ ├── lib/ ← 工具函数库 │ │ └── styles/ ← 全局样式 │ └── package.json └── docs/ ← 文档4.1 server/ —— Rust 后端主战场server/是 WaLiOffice 的绝对核心采用高内聚、低耦合的模块划分方式组织每个目录单一职责main.rs程序入口负责模块声明与启动流程是整个二进制的起点config.rs配置管理解析.env环境变量通过OnceLock实现全局单例保证配置只被读取一次、全局共享state.rs全局状态持有数据库连接池DB Pool与 LLM 客户端LLM Client通过 axum 的 State 提取器注入各路由处理器error.rs统一错误处理定义AppError错误枚举与AppResult类型别名让全链路错误收敛到统一的转换与响应格式routes/HTTP 路由层mod.rs负责构建整个路由表各子模块按业务域拆分例如 Chat 路由与 SSE 流式端点详见 第2-7节后端Chat路由与SSE端点agent/AI Agent 核心承载 ReAct 循环推理 → 行动 → 观察、工具注册表与意图识别是大脑所在详见 第2-5节ReAct循环核心实现 与 第2-4节工具Trait定义与注册表机制llm/LLM 客户端封装 HTTP 调用、流式 SSE 解析与类型定义分为非流式LlmClient与流式LlmStreamClient两条调用链路详见 第2-2节LLM客户端与流式SSE实现db/数据库层基于AnyPool统一 SQLite / MySQL 双数据库连接池内含 6 个 repo 模块每个 repo 对应一组表操作详见 第2-3节数据库设计与会话持久化models/数据模型定义请求 / 响应 DTO隔离 HTTP 层与领域层的数据形态render/文档渲染纯 Rust 渲染 DOCX / XLSX / PPTX 三大办公产物不依赖任何外部服务或命令行工具file_extract.rs附件解析解析用户上传的 PDF、Office 文档、CSV、JSON 附件为附件理解类工具提供内容输入image_ocr.rs图片 OCR对上传图片做文字识别支撑图生图、图文理解等场景auth/认证实现 JWT 认证中间件配合 bcrypt 密码哈希保护用户体系详见 第4-3节用户认证与JWT。这一层模块划分与后端的职责边界一一对应路由层只做 HTTP 编排Agent 层只做智能体决策LLM 层只做模型通信渲染层只做文档产出——每个模块都可以独立替换、独立测试。4.2 migrations/ —— SQL 迁移脚本migrations/存放 SQL 迁移脚本同时覆盖SQLite 与 MySQL两套方言。这背后的设计考量是SQLite 适合本地开发与个人用户零配置、零运维MySQL 适合多用户团队与云端部署并发能力强、运维生态成熟两者各有适用场景因此工程同时维护两套迁移脚本。数据库层的统一访问由sqlx的AnyPool连接池抽象完成上层代码无需感知底层是哪种数据库。4.3 frontend/ —— React TypeScript 前端前端是一个标准的 React 18 TypeScript Vite SPA 工程按api / components / pages / stores / types / config / lib / styles组织代码同样是单一职责的模块化思想api/基于 Axios 封装 HTTP 客户端统一管理请求与错误处理components/UI 组件库包含ChatPanel对话面板、SlidePreview幻灯片预览、ArtifactPanel产物面板等核心组件以及 ECharts 图表、Draw.io 图表、图片 / 视频播放器等产物渲染器pages/页面层其中Studio.tsx是主界面——三栏式工作台左侧会话列表与文件管理中间对话区与附件上传右侧产物预览stores/基于 Zustand 的轻量状态管理适用于会话、流式消息、产物等中等复杂度的前端状态types/TypeScript 类型定义与后端 DTO 对齐保证前后端契约一致config/前端运行配置如 API 地址、上传限制等lib/工具函数库如 SSE 流式解析、图片压缩上传等styles/全局样式配合 TailwindCSS 与 Radix UI 无头组件体系构建高质量 UI。前端与后端通过SSE 流式协议实时通信前端通过fetch ReadableStream解析message / artifact_update / state_update / tool_result / done / project_update等事件类型用户能实时看到 Agent 的思考、工具调用与产物生成过程详见 第2-8节前端对话界面与流式渲染。4.4 docs/ —— 文档docs/存放项目的课程文档与架构说明即读者正在阅读的本系列教程与源码仓库同仓维护做到文档跟着代码走。五、Rust 后端依赖配置Cargo.tomlCargo.toml 是 Rust 工程的项目说明书。结合工程模块划分与各章节文档WaLiOffice 的依赖大致覆盖以下类别各自承担明确的职责依赖类别代表 crate承担职责Web 框架与异步运行时axum、tokio构建异步 Web 服务、路由与并发处理HTTP 客户端reqwestLLM 客户端发起 HTTP 调用文本、图片、视频 API序列化serde、serde_jsonDTO 序列化、工具参数 schema、JSON 产物处理环境变量dotenvy类解析.env配置文件日志tracing、tracing-subscriber结构化日志收集与输出数据库sqlxAnyPoolSQLite MySQL 双数据库统一连接池认证jsonwebtoken、bcryptJWT 签发 / 校验与密码哈希文档渲染docx-rs、rust_xlsxwriter纯 Rust 生成 DOCX / XLSX 文件静态资源嵌入rust-embed前端dist编译期嵌入后端二进制附件与多媒体PDF / Office 解析、图片 OCR、ffmpeg 调用相关依赖支撑file_extract.rs、image_ocr.rs与视频本地兜底注意以上依赖的具体版本号以仓库Cargo.lock锁定的版本为准工程应通过 Cargo.lock 保证构建的可复现性。其中文档渲染的选型动机在 第1-2节 中有明确论述——采用纯 Rust 渲染而不是 Java 的 EasyExcel 或 Python 的 python-docx正是为了不引入额外的外部服务或命令行依赖让渲染发生在同一个进程内零网络开销、零额外故障点。六、程序入口 main.rs模块声明与启动流程main.rs是整个二进制的起点承担模块声明 启动流程两件事模块声明将config、state、error、routes、agent、llm、db、models、render、auth等模块统一在 crate 根声明形成全局可见的模块树启动流程从启动链路看大致顺序为——解析.env环境变量并初始化全局配置OnceLock→ 建立数据库连接池与 LLM 客户端并组装进全局状态AppState→ 注册全部 Agent 工具对应register_all_tools启动流程见 第2-4节→ 构建 axum 路由表 → 绑定端口启动 HTTP 服务 → 通过tracing输出监听日志。启动流程遵循先配置、后状态、再路由的依赖顺序任何一步失败都会在启动期暴露而不是在运行期抛错——这是 Rust 后端工程的一个良好实践。七、config.rs.env 解析与 OnceLock 全局单例配置管理模块解决配置从哪来、如何安全共享的问题来源.env环境变量文件本地开发与部署时通过修改环境变量即可调整行为无需改代码全局单例使用OnceLockRust 标准库提供的一次性初始化容器持有全局配置对象保证配置在整个进程生命周期内只解析一次任何线程读取到的都是同一份不可变配置天然线程安全配置覆盖面从系统架构文档支持多 LLM 端点分离配置文本 / 图片 / 视频独立 API的描述可以推断.env至少会覆盖以下类别——服务监听端口、数据库连接地址、JWT 密钥、文本 LLM 端点API Key / Base URL / 模型名、图片生成 API 端点、视频生成 API 端点等。多组端点分离是为了让不同任务对话、生图、出视频各走各的模型通道互不干扰详见 第4-1节配置管理与多组LLM端点。八、state.rs全局状态共享 DB Pool 与 LLM Clientstate.rs定义AppState全局状态结构持有两类核心资源DB Pool数据库连接池AnyPool所有路由处理器通过它访问 SQLite / MySQL避免每次请求新建连接LLM Client非流式LlmClient与流式LlmStreamClient实例供 ReAct 循环与 SSE 推送使用见 第2-2节。在 axum 中AppState通过State提取器注入路由处理器实现全局共享、只读持有、按需取用是连接配置层与业务层的关键枢纽。九、error.rsAppError 与 AppResult 统一错误处理error.rs定义了AppError统一错误枚举覆盖数据库错误、LLM 调用错误、工具执行错误、参数解析错误、认证错误等各类失败场景AppResultResultT, AppError的类型别名让所有模块的函数签名统一。它的价值在于无论错误发生在哪一层最终都能转换为一致的 HTTP 响应返回给前端同时保留足够的上下文用于tracing日志排查。这是中大型后端工程的基础设施避免每个模块各自为战地抛错误。十、routes/Axum 路由组织方式路由层采用mod.rs聚合 子模块拆分的组织方式routes/mod.rs负责把各子模块的路由组装成完整的 axumRouter统一挂载中间件如 JWT 认证中间件与状态注入各子模块按业务域划分例如 Chat 路由含 SSE 流式端点、认证路由、文件管理路由等每个子模块只关心自己负责的路径段。这种组织方式与目录结构一一呼应新增一个业务域就是新增一个 routes 子模块 在 mod.rs 挂一行路由符合开闭原则也方便按域做单元测试。十一、rust-embed把前端资源打包进后端二进制rust-embed是本节的核心知识点它实现前端独立开发、后端统一打包策略的关键机制编译期嵌入后端构建时rust-embed通过 derive 宏将frontend/构建产出的dist目录静态资源HTML / JS / CSS / 图片等直接嵌入二进制文件运行时静态服务axum 通过 fallback 机制托管这些嵌入资源访问根路径即返回前端页面访问/assets/...即返回静态文件单一二进制最终部署产物只有一个可执行文件包含完整的后端逻辑与前端资源零外部依赖不需要在服务器上安装 Node、拷贝前端目录或配置静态文件服务器。与 Docker 多阶段构建配合node:20构建前端 →rust:1.80编译后端 →debian:bookworm-slim作为运行镜像见 第5-1节Docker多阶段构建这条单一二进制部署链路把运维成本压到了最低——复制一个文件即可完成部署这也是个人与中小企业本地化部署 AI 办公平台非常友好的形态。十二、tracing日志初始化tracing是 Rust 生态的结构化日志与追踪框架在本工程中的初始化要点在main.rs启动早期初始化全局tracing_subscriber设置日志输出格式与级别过滤器通常通过RUST_LOG环境变量控制日志级别之后各模块通过tracing宏info!/warn!/error!/debug!输出带模块路径、字段上下文的日志相比简单的 printlntracing支持结构化字段与 Span 追踪能把一次 HTTP 请求或一轮 Agent 循环的关键步骤串联起来为排查LLM 调用为什么超时工具执行到哪一步失败了这类问题提供依据。结合error.rs的统一错误类型日志与错误处理形成闭环错误产生时记录结构化日志前端收到统一错误响应运维在日志中定位根因。十三、这一节为后续章节打下的地基工程初始化不是终点而是后续所有功能的载体。以本节脚手架为基础WaLiOffice 课程后续逐步填肉智能体对话基础第 2 部分LLM 客户端与流式 SSE第2-2节→ 数据库与会话持久化第2-3节→ 工具 Trait 与注册表第2-4节→ ReAct 循环第2-5节→ 意图识别第2-6节→ Chat 路由与 SSE 端点第2-7节→ 前端对话界面第2-8节工具集成第 3 部分在agent/工具注册表之上注册 Markdown、Word、PPT、Excel、ECharts 图表、Draw.io、图像、视频、联网搜索等 10 个业务工具底层渲染复用render/模块增强设计第 4 部分多组 LLM 端点配置第4-1节、附件处理第4-2节、JWT 认证第4-3节部署与 DevOps第 5 部分Docker 多阶段构建与云服务器部署配置第5-1节 / 第5-2节。可以说本节搭建的server/分层agent / llm / db / render / routes / auth与frontend/分层pages / components / stores / api / types就是整个 WaLiOffice 的钢筋骨架后续每一节新增的能力都能在骨架中找到自己的落点这正是一个从 0 到 1 的 AI Agent 项目最值得先想清楚的部分。赞分享文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载相关推荐Sunshine 实战指南从安装到跑通6步走完核心串流链路Sunshine 实战指南从安装到跑通6步走完核心串流链路 Sunshine 是一款自托管游戏串流服务器配合 Moonlight 客户端让你用手机、电视音视频后端Vencord脚手架工具与项目初始化Vencord脚手架工具与项目初始化 引言为什么需要专业的脚手架工具 还在为Discord客户端修改项目的复杂配置而头疼吗还在手动搭建开发环境、处理依赖冲即时通讯桌面应用前端插件系统Tauri 开发速查手册初始化脚手架、调试手段、安卓打包与配置结构全解析jaywcjlove/reference 备忘清单精讲Tauri 开发速查手册初始化脚手架、调试手段、安卓打包与配置结构全解析jaywcjlove/reference 备忘清单精讲 本篇技术指南以 jaywc文档知识库教程开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考