AI Agent 课程文档

切换日光/暗黑模式

003. 导入数据并启动后端 ​

学习目标 ​

这一节把 MariaDB 连起来、导入初始数据，并让本地后端项目先跑通。

学完后，你应该能理解：

  • 为什么后端开发建议使用 PyCharm；
  • DataGrip / Database 工具在数据库调试里负责什么；
  • Docker 容器和宿主机目录为什么看起来不一样；
  • SQL 文件导入数据库的本质是什么；
  • .env.example 和 .env 的关系；
  • 为什么 Python 项目需要单独的 Conda 环境；
  • 后端入口文件和前端 main.ts / index.ts 的类比关系。

开发工具准备 ​

后端工程主要使用 PyCharm。

PyCharm 相比通用编辑器更适合 Python 后端开发，尤其是：

  • Python 解释器管理；
  • Conda 环境绑定；
  • 包依赖提示；
  • 运行配置；
  • Database 数据库工具；
  • 后续调试 FastAPI、SQLModel、LangChain 等代码。

如果你平时只写 JS，可能更熟悉 VS Code。前端项目继续用 VS Code、WebStorm 或自己顺手的工具都可以，但后端建议跟着 PyCharm 走，减少环境差异。

为什么需要能访问官方文档？ ​

AI Agent 开发会接触很多框架和服务，例如 LangGraph、FastAPI、LlamaIndex、Dify 等。

课程资料不会把每个 API 都完整翻译一遍。真正写项目时，你需要能查看官方文档，确认：

  • 函数怎么调用；
  • 参数是什么；
  • 返回值是什么；
  • 版本之间有没有变化；
  • 示例代码是不是适合当前项目。

这和前端开发查 React、Vue、Vite、Ant Design 文档是一样的。AI 可以帮你解释文档，但你仍然要知道资料从哪里来。

保存服务器信息 ​

学习阶段会频繁打开多个地址和账号信息，建议为当前服务器建一个专门的记录文件夹或笔记。

至少记录：

  • 云服务器控制台地址；
  • 服务器 IP；
  • 宝塔面板地址；
  • SSH 连接信息；
  • 数据库外部端口；
  • 模型平台 Key 存放位置；
  • 后端、前端、静态资源部署目录。

这不是形式主义。后面排查问题时，最浪费时间的往往不是代码，而是忘了某个端口、密码、路径或控制台入口。

用 PyCharm 连接 MariaDB ​

PyCharm 内置 Database 工具，能力接近 DataGrip。

连接 MariaDB 时，需要填：

配置含义
Host服务器 IP
Port映射出来的服务器端口，比如 14148
User数据库用户名
Password数据库密码
Database要连接的业务数据库

如果连接失败，优先检查：

  • 数据库容器是否正在运行；
  • Docker 端口映射是否正确；
  • 云服务器防火墙是否放开端口；
  • 用户名和密码是否填错；
  • 本地网络是否能访问服务器。

进入 Docker 容器 ​

导入 SQL 数据时，需要进入 MariaDB 容器。

容器可以理解成一个独立的小 Linux 环境。进入容器前，你在服务器宿主机里；进入容器后，你看到的是容器自己的目录结构。

常见命令形式：

bash
docker exec -it mysql bash

含义可以拆开理解：

片段含义
docker exec在一个正在运行的容器里执行命令
-it以交互方式进入，方便输入命令
mysql容器名称
bash进入容器里的命令行

进入后，命令行前缀会变成容器 ID 或容器名，这表示你已经不在宿主机环境里了。

容器目录和宿主机目录 ​

课程里会进入类似目录：

bash
/var/lib/mysql

这是容器里的数据目录。

但因为前面做了目录映射，这个目录对应宿主机上的某个目录，例如：

bash
/www/app/mysql

所以你可以从两个角度理解同一份数据：

  • 容器视角：数据在 /var/lib/mysql；
  • 服务器视角：数据在 /www/app/mysql。

这是 Docker 目录映射最核心的理解点。

下载并导入 SQL 文件 ​

初始数据通常会以 SQL 文件形式提供。

SQL 文件本质上是一堆 SQL 语句。导入数据，就是让数据库执行这些 SQL 语句。

典型流程是：

  1. 进入 MariaDB 容器；
  2. 进入数据目录；
  3. 使用 wget 下载 SQL 压缩包或 SQL 文件；
  4. 解压文件；
  5. 登录 MariaDB 命令行；
  6. 创建业务数据库；
  7. 切换到业务数据库；
  8. 执行 SQL 文件。

常见 SQL 命令：

sql
create database prime;
use prime;
source xxx.sql;

source 的意思是执行某个 SQL 文件里的所有 SQL 语句。

在数据库工具里修改数据 ​

用 PyCharm Database 工具打开表后，可以直接查看和编辑数据。

要注意：

  • 表格里改了值，不一定马上写入数据库；
  • 通常需要点击提交按钮；
  • 提交后再刷新，才能确认数据库里真的变了；
  • 不要把临时测试数据误以为已经保存。

对前端同学来说，可以类比浏览器表单：你在输入框里改了值，不代表后端数据库已经更新，必须真正提交请求才算写入。

配置后端 .env ​

后端项目通常会提供 .env.example。

它是配置模板，不是真正运行用的配置。实际运行前要复制一份：

bash
.env.example -> .env

.env 里会放：

  • 数据库 Host；
  • 数据库 Port；
  • 数据库用户名；
  • 数据库密码；
  • 数据库名；
  • Redis 配置；
  • PostgreSQL 配置；
  • Milvus 配置；
  • 模型平台 Key。

当前阶段只先打开 MariaDB 相关配置，其他还没安装的服务可以先注释掉对应检查代码或连接配置。

后端入口文件 ​

后端项目里会有一个入口文件，比如 server.py。

可以类比前端项目里的：

  • main.ts
  • main.tsx
  • index.ts

前端入口负责创建 React / Vue 应用；后端入口负责启动 FastAPI 服务。

第一次运行时，不要只点 Run。要先确认运行配置：

  • Python 解释器是不是当前项目的 Conda 环境；
  • 工作目录是不是项目根目录；
  • 环境变量是否正确；
  • 入口文件是否选对。

创建 Conda 环境 ​

Python 项目不要直接使用系统 Python。

课程里为后端项目单独创建 Conda 环境，例如：

bash
conda create -n ai2 python=3.11
conda activate ai2

使用 Python 3.11，是为了兼容项目依赖。太新的 Python 版本可能会遇到部分包还没适配的问题，太旧的版本又可能缺少新特性。

Conda 环境可以理解成 Node 项目的独立依赖空间：

  • 当前项目安装的包只进当前环境；
  • 不影响其他 Python 项目；
  • 环境坏了可以重新建；
  • 更容易复现课程里的运行状态。

安装依赖并运行 ​

后端项目会使用 Poetry 管理依赖。

大致流程是：

bash
pip install poetry
poetry install

安装完成后，PyCharm 里选中这个 Conda 环境作为项目解释器，再运行后端入口文件。

运行成功后，可以访问 FastAPI 自动生成的接口文档页面。这个页面会列出后端暴露的 API，方便后续调试。

当前阶段先跑通数据库连接和服务启动，不急着理解每个接口的业务含义。

AI Agent 课程学习文档。

Copyright © 2026