Relevant source files

The following files were used as context for generating this wiki page: - [DEVELOPMENT.md](https://github.com/microsoft/data-formulator/blob/main/DEVELOPMENT.md) - [py-src/data_formulator/data_loader/mysql_data_loader.py](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/mysql_data_loader.py) - [src/views/EncodingShelfCard.tsx](https://github.com/microsoft/data-formulator/blob/main/src/views/EncodingShelfCard.tsx) - [py-src/data_formulator/data_loader/mssql_data_loader.py](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/mssql_data_loader.py) - [local_server.bat](https://github.com/microsoft/data-formulator/blob/main/local_server.bat) - [py-src/data_formulator/data_loader/postgresql_data_loader.py](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/postgresql_data_loader.py) - [pyproject.toml](https://github.com/microsoft/data-formulator/blob/main/pyproject.toml) - [requirements.txt](https://github.com/microsoft/data-formulator/blob/main/requirements.txt) - [local_server.sh](https://github.com/microsoft/data_formulator/blob/main/local_server.sh) - [api-keys.env.template](https://github.com/microsoft/data-formulator/blob/main/api-keys.env.template)

# 安装指南本指南将引导您完成 Data Formulator 的本地开发环境搭建、依赖安装、配置以及生产环境部署的全过程。Data Formulator 是一个由 AI 驱动的数据可视化工具，其架构包含 Python 后端和 TypeScript 前端。 ## 系统要求在开始之前，请确保您的系统已安装以下核心软件： | 软件 | 最低版本 | 推荐版本 | 用途 | | :------- | :------- | :------- | :------------- | | Python | 3.11 | 最新版 | 后端运行环境 | | Node.js | 18.x | LTS 版 | 前端构建环境 | | Yarn | 1.22.x | 最新版 | 前端包管理器 | ## 安装流程概览 Data Formulator 的安装和配置过程可以概括为以下几个主要步骤。下图展示了从环境准备到运行应用的完整流程： ```mermaid graph TB A[1. 环境准备
安装 Python, Node.js, Yarn] --> B[2. 克隆项目
获取源代码] B --> C[3. 后端设置
创建虚拟环境 & 安装依赖] C --> D[4. 配置环境变量
API密钥 & 数据库] D --> E[5. 前端设置
安装 NPM 包] E --> F{选择运行模式} F --> G[开发模式
后端 & 前端分离运行] F --> H[生产模式
构建并运行单体应用] G --> I[访问应用
http:#47;#47;localhost:5173] H --> J[访问应用
http:#47;#47;localhost:5000] ``` ## 后端设置后端基于 Python 构建，负责数据处理、AI 模型交互和 API 服务。 ### 1. 创建并激活虚拟环境为了避免依赖冲突，强烈建议在 Python 虚拟环境中进行开发。 **Windows:** ```bash python -m venv venv .\venv\Scripts\activate ``` **macOS / Linux:** ```bash python -m venv venv source venv/bin/activate ``` ### 2. 安装 Python 依赖激活虚拟环境后，使用 `pip` 安装项目所需的所有 Python 包。这些依赖项在 [`requirements.txt`](https://github.com/microsoft/data-formulator/blob/main/requirements.txt) 文件中列出。 ```bash pip install -r requirements.txt ``` 此命令会安装包括 Flask、Pandas、LiteLLM、DuckDB 以及各种数据库连接器（如 `pymysql`, `pyodbc`）在内的所有必要库。 ### 3. 配置环境变量您可以通过环境变量来配置 Data Formulator 的行为，例如 API 密钥和数据库连接。 #### API 密钥配置为了使 Data Formulator 能够调用 AI 模型，您需要配置相应的 API 密钥。 1. 复制模板文件： ```bash cp api-keys.env.template api-keys.env ``` 2. 编辑 `api-keys.env` 文件，填入您的 API 密钥。该文件支持多种 AI 服务提供商，如 OpenAI、Azure OpenAI、Anthropic 等。请参考 [`api-keys.env.template`](https://github.com/microsoft/data-formulator/blob/main/api-keys.env.template) 中的示例进行配置。 #### 服务器属性配置您还可以通过 `.env` 文件配置服务器的高级属性。 1. 复制模板文件： ```bash cp .env.template .env ``` 2. 根据需要修改 `.env` 文件中的设置。关键配置项包括： - `DISABLE_DISPLAY_KEYS`: 如果为 `true`，前端将不会显示 API 密钥。 - `EXEC_PYTHON_IN_SUBPROCESS`: 如果为 `true`，Python 代码将在子进程中执行（更安全但更慢）。 - `LOCAL_DB_DIR`: 用于存储本地数据库文件的目录（如果未设置，则使用临时目录）。 - **外部数据库设置** (当 `USE_EXTERNAL_DB=true` 时): - `DB_TYPE`: 数据库类型，支持 `mysql` 或 `postgresql`。 - `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USER`, `DB_PASSWORD`: 数据库连接信息。 ## 前端设置前端基于 TypeScript 和 React 构建，负责用户界面和交互。 ### 安装 NPM 包在项目根目录下，使用 `yarn` 安装所有前端依赖。 ```bash yarn ``` ## 运行应用根据您的需求，可以选择在开发模式或生产模式下运行 Data Formulator。 ### 开发模式开发模式允许您实时修改代码并立即看到效果，非常适合前端和后端的协同开发。 1. **启动后端服务器**: 在一个终端中，运行以下脚本启动 Python 后端服务。 **Windows:** ```bash .\local_server.bat ``` **macOS / Linux:** ```bash ./local_server.sh ``` 这些脚本会设置 `FLASK_RUN_PORT=5000` 并以开发模式启动应用。 2. **启动前端开发服务器**: 在另一个终端中，运行以下命令启动前端开发服务器。 ```bash yarn start ``` 这将启动一个热重载的开发服务器，通常在 [http://localhost:5173](http://localhost:5173) 上运行。 ### 生产模式生产模式会将前端代码构建为静态文件，并由 Python 后端统一提供服务，形成一个单一的应用程序。 1. **构建前端**: ```bash yarn build ``` 此命令会将 TypeScript 和 React 代码编译并打包到 `py-src/data_formulator/dist` 目录。 2. **构建 Python 包**: ```bash pip install build python -m build ``` 这会在 `dist/` 目录下创建一个 Python wheel 文件（例如 `data_formulator--py3-none-any.whl`）。 3. **安装并运行**: 您可以在一个新的虚拟环境中测试构建好的包。 ```bash # 安装构建好的 wheel 文件 pip install dist/data_formulator--py3-none-any.whl # 运行应用 data_formulator # 或者 python -m data_formulator ``` 应用将在 [http://localhost:5000](http://localhost:5000) 上提供服务。 ## 数据库连接器配置 Data Formulator 支持通过 DuckDB 连接到多种外部数据库。以下是一些常见数据库的配置说明。 ### MySQL 要连接到 MySQL 数据库，您需要安装 `pymysql` 库（已包含在 `requirements.txt` 中）。连接参数通常包括： - `host`: MySQL 服务器地址 (默认: `localhost`) - `port`: 端口 (默认: `3306`) - `user`: 用户名 (默认: `root`) - `password`: 密码 - `database`: 要连接的数据库名详细的连接说明和故障排除指南，请参考 [`mysql_data_loader.py`](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/mysql_data_loader.py) 中的 `auth_instructions` 方法。 ### PostgreSQL 连接 PostgreSQL 数据库需要通过 DuckDB 的 `postgres` 扩展。连接参数通常包括： - `host`: 服务器地址 (默认: `localhost`) - `port`: 端口 (默认: `5432`) - `user`: 用户名 (默认: `postgres`) - `password`: 密码 - `database`: 数据库名实现细节请参考 [`postgresql_data_loader.py`](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/postgresql_data_loader.py)。 ### SQL Server (MSSQL) 连接 SQL Server 需要安装 `pyodbc` 库（已包含在 `requirements.txt` 中）。连接参数通常包括： - `server`: 服务器地址或实例名 (默认: `localhost`) - `database`: 数据库名 (默认: `master`) - `user`: 用户名 (留空则使用 Windows 认证) - `password`: 密码 (留空则使用 Windows 认证) - `driver`: ODBC 驱动名称 (默认: `ODBC Driver 17 for SQL Server`) 详细的连接说明、驱动安装和故障排除指南，请参考 [`mssql_data_loader.py`](https://github.com/microsoft/data-formulator/blob/main/py-src/data_formulator/data_loader/mssql_data_loader.py) 中的 `auth_instructions` 方法。 ## 生产环境部署安全注意事项 ⚠️ **重要安全警告** 将 Data Formulator 部署到生产环境时，请务必考虑以下安全因素： 1. **数据库存储安全**: 默认情况下，Data Formulator 会在服务器本地存储 DuckDB 文件，其中包含用户数据。在多租户环境中这可能存在安全风险。 2. **会话管理**: 当启用数据库时，会话 ID 存储在 Flask 会话中并与本地 DuckDB 文件关联。 3. **数据持久性**: 用户数据可能会临时存储在这些本地文件中。 **推荐的安全措施**: - 对于不需要数据持久化的无状态部署，请使用 `--disable-database` 标志。 - 实施适当的身份验证、授权和其他安全措施，例如用户认证、基于角色的访问控制、API 速率限制和 HTTPS/TLS 加密。 **无状态部署配置示例**: ```bash python -m data_formulator.app --disable-database ``` ## 总结通过遵循本指南，您应该能够成功地在本地设置 Data Formulator 的开发环境，并了解如何将其打包和部署到生产环境。从安装依赖、配置环境变量到选择合适的运行模式，每一步都至关重要。请务必注意生产环境中的安全配置，以保护您的数据和系统安全。