Vanna 在 Docker 上的部署记录与问题解决指南
一、部署思路
- 环境搭建：确保本地系统安装有 Docker 环境，且 Python 版本为 3.13.3。选用 ollama 服务的 deepseek-r1:32b 模型，采用免费的 ChromaDB 开源矢量数据库，同时以本地 MySQL 数据库作为关系型数据库来存放测试数据。
- 获取部署代码：从 Vanna 官网依据所选环境获取官方部署代码。
- 安装依赖：执行
pip install vanna[chromadb,ollama,mysql]命令，安装 vanna 库及其相关依赖，包含向量数据库和 ollama 所需的依赖。 - 配置连接信息：在代码中配置 ollama_host、MySQL 连接信息（host、dbname、user、password、port）等参数，保障应用能正确连接到各个服务。其中，MySQL 的 host、password 等信息需根据实际情况替换为自己的设置，ollama_host 也需根据实际部署环境调整。
- 启动服务：通过编写代码启动内置的集成 flask 框架的 web 界面，以此实现 Vanna 的功能。
- 模型训练：首次启动时对 ddl 和 sql 文本进行训练，后续启动需注释掉首次训练代码。训练可通过在代码中添加
vn.train语句，或者在 web 界面的 training data 中添加 ddl、文本和 sql 语句这两种方式进行。
二、遇到的问题及解决方法
（一）MySQL 连接问题
- 问题描述：执行
docker run -p 5000:5000 vanna-app时，出现pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)")错误。 - 问题分析：可能是 MySQL 服务器未运行、连接地址或端口错误、权限问题、防火墙或安全组设置、Docker 网络问题（若 MySQL 也在 Docker 中运行）等原因导致。
- 解决方法：
- 检查 MySQL 服务状态，确保其已启动。
- 确认连接地址和端口正确，若 MySQL 在其他机器上，修改
localhost为实际 IP 地址。 - 检查用户名和密码是否正确，确保用户有连接权限，可在 MySQL 中使用
GRANT语句授予权限。例如GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'your_host' IDENTIFIED BY 'your_password';，其中your_database、your_user、your_host、your_password都需要替换为真实信息。 - 检查防火墙或安全组设置，允许应用程序连接到 MySQL 服务器的端口（默认 3306）。
- 若 MySQL 在 Docker 容器中，确保应用程序所在容器和 MySQL 容器在同一网络，或通过正确网络配置访问 MySQL 容器。
（二）端口冲突问题
- 问题描述：启动容器时出现
(HTTP code 500) server error - failed to set up container networking: driver failed programming external connectivity on endpoint interesting_rubin (f64551c16b55015b0d82d1d0ced16ea0e891d87a30c9788c451e7f567934cfd7): Bind for 0.0.0.0:5000 failed: port is already allocated错误。 - 问题分析：宿主机的 5000 端口已被其他进程占用，导致容器端口映射失败。
- 解决方法：
- 使用
netstat -ano | findstr :5000（Windows）或sudo lsof -i :5000（Linux）查找占用 5000 端口的进程，并结束该进程。 - 修改容器端口映射，如将
docker run -p 5000:5000 vanna-app改为docker run -p 5001:5000 vanna-app，将容器的 5000 端口映射到宿主机的 5001 端口。
- 使用
（三）MySQL 权限问题
- 问题描述：出现
pymysql.err.OperationalError: (1130, "Host 'host.docker.internal' is not allowed to connect to this MySQL server")错误。 - 问题分析：MySQL 服务器拒绝了来自
host.docker.internal（容器内指代宿主机的特殊域名）的连接请求，是由于 MySQL 权限设置问题导致。 - 解决方法：
- 登录 MySQL 服务器，执行
GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'your_host' IDENTIFIED BY 'your_password';（将your_host替换为实际允许连接的主机地址，your_user、your_password、your_database替换为真实的用户名、密码和数据库名）授予权限。若要允许从任何主机连接，可使用'%'通配符。 - 执行
FLUSH PRIVILEGES;使权限设置生效。
- 登录 MySQL 服务器，执行
（四）缺少依赖问题
- 问题描述：出现
RuntimeError: 'cryptography' package is required for sha256_password or caching_sha2_password auth methods错误。 - 问题分析：应用程序使用了
sha256_password或caching_sha2_password认证方法，代码中缺少cryptography包。 - 解决方法：在
requirements.txt文件中添加cryptography包，重新构建 Docker 镜像。
（五）Flask 应用访问问题
- 问题描述：访问
http://localhost:8084无法打开页面。 - 问题分析：可能是端口不一致、应用未完全启动或出错、防火墙或安全软件限制、网络连接问题、Flask 应用配置问题等原因导致。
- 解决方法：
- 确认应用监听端口和
docker run命令中的端口映射正确。 - 查看 Docker 容器日志，获取更多报错信息。
- 检查系统防火墙和安全软件设置，允许对相应端口的访问。
- 确认网络连接正常，检查容器网络配置。
- 确保 Flask 应用
host参数设置为0.0.0.0，检查路由等配置是否正确。
- 确认应用监听端口和
三、Dockerfile 配置说明
在 Vanna 部署到 Docker 的过程中，Dockerfile大致会包含以下关键部分：
- 基础镜像选择：由于 Vanna 需要运行在 Python 3.13.3 环境下，通常会以官方的 Python 3.13.3 镜像作为基础，例如：
Dockerfile
FROM python:3.13.3-slim
这确保了容器内有合适的 Python 运行环境。
2. 安装系统依赖（如有需要）：部分 Python 库在安装或运行时可能依赖系统级别的工具或库。例如，在安装某些带有 C 扩展的 Python 库时，可能需要gcc、make等工具。因此，Dockerfile中可能会包含安装这些工具的指令，如在基于 Debian 的镜像中：
Dockerfile
RUN apt-get update && apt-get install -y
gcc
make
&& rm -rf /var/lib/apt/lists/*
- 设置工作目录：为了组织项目文件，会在容器内创建一个工作目录，并将项目文件复制进去。假设项目文件位于宿主机的当前目录：
Dockerfile
WORKDIR /app
COPY. /app
- 安装 Python 依赖：根据项目需求，
Dockerfile会通过requirements.txt文件安装 Python 依赖。前面提到需要安装vanna[chromadb,ollama,mysql]库，所以Dockerfile中会有类似这样的指令：
Dockerfile
COPY requirements.txt.
RUN pip install -r requirements.txt
这一步确保了容器内安装了 Vanna 运行所需的所有 Python 包。
四、requirements.txt 配置说明
requirements.txt文件在 Vanna 的 Docker 部署中起着管理 Python 依赖的关键作用。从部署过程可知，需要安装vanna[chromadb,ollama,mysql]库，因此requirements.txt文件中至少应包含：
- 核心库
vanna：明确指定vanna库及其可能的版本（若有特定版本要求），以确保安装的是符合项目需求的版本，例如：
plaintext
vanna[chromadb,ollama,mysql]
这将安装带有chromadb、ollama和mysql相关功能支持的vanna库。
2. 相关依赖包：除了vanna库本身，chromadb、ollama相关的依赖以及mysql的驱动（如pymysql）也会被安装。虽然在实际操作中没有明确列出所有这些依赖包，但根据vanna库的功能需求和常见的 Python 库依赖关系，requirements.txt文件可能还会包含：
plaintext
chromadb
pymysql
此外，当遇到缺少cryptography包的问题时，在requirements.txt文件中添加cryptography包解决了问题，说明这个文件是集中管理项目 Python 依赖的地方。所以，如果项目还有其他特殊的依赖，也应添加到这个文件中，然后重新构建镜像使新的依赖生效。
