ax-backend/docs/environment-setup.md

环境配置指南

前置条件

• Anaconda 或 Miniconda 已安装
• Git 已安装

---

1. 创建 Conda 环境

conda create -n ax-backend python=3.11 -y

Python 版本要求 3.10+，推荐使用 3.11。

---

2. 激活环境

conda activate ax-backend

激活后终端提示符前应显示 (ax-backend)。

---

3. 安装依赖

进入项目根目录后安装 requirements.txt：

cd d:/code/ax-backend
pip install -r requirements.txt

weasyprint 在 Windows 上依赖 GTK 运行时，若安装报错见下方常见问题。

---

4. 配置环境变量

复制示例文件并按实际情况填写：

cp .env.example .env

.env 关键配置项：

# 数据库
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/ax_backend

# Redis（阶段 2 引入）
REDIS_URL=redis://localhost:6379/0

# JWT 密钥（阶段 2 引入，生产环境务必替换）
JWT_SECRET_KEY=your-secret-key-here

# 文件存储路径（模板上传，阶段 1 引入）
TEMPLATE_STORAGE_PATH=./storage/templates

---

5. 初始化数据库

确保 PostgreSQL 已启动，并已创建对应数据库，然后执行 Alembic 迁移：

alembic upgrade head

---

6. 启动服务

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

服务启动后访问：

• API 文档（Swagger）：http://localhost:8000/docs
• 备用文档（ReDoc）：http://localhost:8000/redoc

---

7. 验证安装

python -c "import fastapi, sqlalchemy, pydantic; print('OK')"

输出 OK 即表示核心依赖安装正常。

---

常见问题

weasyprint 在 Windows 上安装失败

weasyprint 依赖 GTK3 运行时，Windows 需要额外安装：

1. 下载并安装 GTK3 Runtime for Windows
2. 安装完成后重新执行 pip install weasyprint==63.1

weasyprint 仅在阶段 3（PDF 导出）用到，阶段 0/1/2 开发可暂时跳过，注释掉 requirements.txt 中对应行即可。

asyncpg 编译失败

asyncpg 需要 C 编译器。Windows 上推荐安装预编译包：

pip install asyncpg --prefer-binary

conda activate 不生效（Windows CMD）

在 CMD 中需先初始化：

conda init cmd.exe

关闭并重新打开终端后再执行 conda activate ax-backend。

---

退出环境

conda deactivate

删除环境

conda remove -n ax-backend --all -y