前言

在了解整体架构后，本文将带你从零搭建"鸿蒙壁纸大师"的开发环境。从项目初始化、依赖安装到环境变量配置，再到 Docker 部署，完整呈现一个生产级 Python 项目的环境搭建全过程。

一个好的开始是成功的一半。规范的环境搭建能避免后续开发中 80% 的"环境问题"。

一、项目初始化

1.1 创建项目目录

# 创建项目目录结构
mkdir -p ai-wallpaper-server/{core,config,models,routes,services,utils,tests}

# 初始化 Python 项目
cd ai-wallpaper-server
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

1.2 依赖管理

# requirements.txt - 项目依赖
fastapi>=0.109.0        # Web 框架
uvicorn>=0.27.0         # ASGI 服务器
httpx>=0.26.0           # 异步 HTTP 客户端
pydantic>=2.5.3         # 数据验证
python-dotenv>=1.0.0    # 环境变量管理
a2a-sdk>=0.1.0          # A2A SDK（可选）

安装依赖：

# 安装所有依赖
pip install -r requirements.txt

# 开发环境额外依赖
pip install pytest pytest-asyncio  # 测试框架

# 冻结依赖版本（用于部署）
pip freeze > requirements.lock.txt

上图展示了从项目初始化到 Docker 部署的完整环境搭建流程

二、环境变量配置

2.1 .env 文件

# .env - 环境变量配置（禁止提交到版本控制）

# 服务配置
HOST=0.0.0.0
PORT=8080
ENVIRONMENT=development

# 火山引擎 API 配置（必填）
VOLCANIC_API_KEY=your_volcanic_api_key_here
VOLCANIC_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

# 模型配置
LANGUAGE_MODEL=doubao-seed-2-0-mini-250115    # 语言模型
INTENT_MODEL=doubao-lite-4k                    # 意图识别模型（轻量省钱）
IMAGE_MODEL=doubao-seedream-5-0-260128         # 文生图模型

# 意图识别配置
INTENT_USE_LLM=true
INTENT_CONFIDENCE_THRESHOLD=0.6

# 日志级别
LOG_LEVEL=INFO

# 设备分辨率（可选覆盖）
# DEVICE_RESOLUTION={"phone":"1080x3414","tablet":"1600x2560"}
DEFAULT_RESOLUTION=1080x2400

# 华为 Webhook 推送配置（可选，用于异步推送）
WEBHOOK_API_KEY=
WEBHOOK_API_SECRET=
WEBHOOK_API_ID=
WEBHOOK_PUSH_ID=

2.2 Settings 配置类

# core/config.py - 配置管理

import os
from typing import Optional, Dict
from dotenv import load_dotenv

# 加载 .env 文件
load_dotenv()


class Settings:
    """应用配置"""

    def __init__(self):
        # 服务配置
        self.HOST = os.getenv("HOST", "0.0.0.0")
        self.PORT = int(os.getenv("PORT", "8080"))

        # 火山引擎配置
        self.VOLCANIC_API_KEY = os.getenv("VOLCANIC_API_KEY", "")
        self.VOLCANIC_BASE_URL = os.getenv(
            "VOLCANIC_BASE_URL",
            "https://ark.cn-beijing.volces.com/api/v3"
        )

        # 模型配置
        self.LANGUAGE_MODEL = os.getenv(
            "LANGUAGE_MODEL",
            "doubao-seed-2-0-mini-250115"
        )
        self.INTENT_MODEL = os.getenv("INTENT_MODEL", "doubao-lite-4k")
        self.IMAGE_MODEL = os.getenv(
            "IMAGE_MODEL",
            "doubao-seedream-5-0-260128"
        )

        # 意图识别配置
        self.INTENT_USE_LLM = os.getenv("INTENT_USE_LLM", "true").lower() == "true"
        self.INTENT_CONFIDENCE_THRESHOLD = float(
            os.getenv("INTENT_CONFIDENCE_THRESHOLD", "0.6")
        )

        # 日志级别
        self.LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()

        # 设备分辨率
        self.DEFAULT_RESOLUTION = os.getenv("DEFAULT_RESOLUTION", "1080x2400")

        # Webhook 推送
        self.WEBHOOK_API_KEY = os.getenv("WEBHOOK_API_KEY", "")
        self.WEBHOOK_API_SECRET = os.getenv("WEBHOOK_API_SECRET", "")
        self.WEBHOOK_API_ID = os.getenv("WEBHOOK_API_ID", "")
        self.WEBHOOK_PUSH_ID = os.getenv("WEBHOOK_PUSH_ID", "")

    @property
    def is_production(self) -> bool:
        return os.getenv("ENVIRONMENT", "development") == "production"


# 全局配置实例
settings = Settings()

2.3 配置验证

配置验证是确保服务启动前所有必要参数都已正确设置的关键步骤。以下代码在应用启动时自动检查配置完整性：

# config_check.py - 启动前检查配置完整性

from core.config import settings


def check_config():
    """检查配置完整性"""
    errors = []
    warnings = []

    # 必填配置检查
    if not settings.VOLCANIC_API_KEY:
        errors.append("VOLCANIC_API_KEY 未配置，AI 功能无法使用")

    if not settings.VOLCANIC_BASE_URL:
        errors.append("VOLCANIC_BASE_URL 未配置")

    # 模型配置检查
    if not settings.LANGUAGE_MODEL:
        warnings.append("LANGUAGE_MODEL 未配置，使用默认值")

    # Webhook 配置检查
    if not all([settings.WEBHOOK_API_KEY, settings.WEBHOOK_API_SECRET,
                settings.WEBHOOK_API_ID]):
        warnings.append("Webhook 推送配置不完整，推送功能不可用")

    # 输出结果
    if errors:
        print("配置错误:")
        for error in errors:
            print(f"  - [ERROR] {error}")
        return False

    if warnings:
        print("配置警告:")
        for warning in warnings:
            print(f"  - [WARN] {warning}")

    print("配置检查通过")
    return True


if __name__ == "__main__":
    check_config()

三、火山引擎 API 配置

3.1 获取 API Key

# 步骤 1：注册火山引擎账号
# 访问 https://console.volcengine.com/

# 步骤 2：开通豆包大模型服务
# 进入"火山方舟"控制台
# 选择需要使用的模型（doubao-seed-2-0-mini, doubao-seedream-5-0 等）

# 步骤 3：创建 API Key
# 进入"API Key 管理"→ 创建新的 API Key
# 复制 API Key 到 .env 文件的 VOLCANIC_API_KEY

# 步骤 4：测试 API 连通性
curl -X POST https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VOLCANIC_API_KEY" \
  -d '{
    "model": "doubao-lite-4k",
    "messages": [{"role": "user", "content": "你好"}]
  }'

3.2 三种模型的选择策略

# 模型选择策略说明

"""
本项目中使用了三种不同的模型，各有分工：

1. LANGUAGE_MODEL (doubao-seed-2-0-mini)
   - 用途：闲聊对话、提示词优化
   - 特点：性价比高，适合文本生成
   - 成本：中等
   - 选型理由：壁纸优化提示词需要一定的创作能力

2. INTENT_MODEL (doubao-lite-4k)
   - 用途：用户意图分类（7种意图）
   - 特点：轻量快速，成本极低
   - 成本：低
   - 选型理由：意图识别是简单分类任务，不需要大模型

3. IMAGE_MODEL (doubao-seedream-5-0)
   - 用途：文生图（壁纸生成）
   - 特点：专业的图像生成模型
   - 成本：高（按张计费）
   - 选型理由：壁纸生成是核心功能，需要高质量输出
"""

四、Docker 部署配置

4.1 Dockerfile

# Dockerfile - 生产环境构建

FROM python:3.11-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

# 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 创建环境变量文件（如果不存在）
RUN if [ ! -f .env ]; then \
    cp .env.example .env; \
    fi

EXPOSE 8000

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# 启动应用
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

4.2 Docker Compose

# docker-compose.yml - 服务编排

version: '3.8'

services:
  ai-wallpaper:
    build: .
    container_name: ai-wallpaper
    ports:
      - "8000:8000"
    environment:
      - VOLCANIC_API_KEY=${VOLCANIC_API_KEY:-}
      - VOLCANIC_BASE_URL=${VOLCANIC_BASE_URL:-https://ark.cn-beijing.volces.com/api/v3}
      - PORT=8000
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - ai-wallpaper-network

networks:
  ai-wallpaper-network:
    driver: bridge

4.3 构建与运行

# 本地开发
source venv/bin/activate
uvicorn main:app --host 0.0.0.0 --port 8080 --reload

# Docker 构建
docker build -t ai-wallpaper:latest .

# Docker Compose 启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 检查健康状态
curl http://localhost:8000/health
# 预期：{"status": "ok", "message": "Service is healthy"}

五、日志系统配置

5.1 多文件日志

# utils/logger.py - 日志配置

import logging
import sys
import os
from datetime import datetime
from contextvars import ContextVar

# 日志目录
LOG_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "logs")
os.makedirs(LOG_DIR, exist_ok=True)

# 当前 sessionId 上下文
_session_id: ContextVar = ContextVar("session_id", default=None)

# 日志格式
LOG_FORMAT = "%(asctime)s | %(levelname)-8s | %(name)s | %(sessionId)s | %(message)s"


def setup_logger(name: str, filename: str) -> logging.Logger:
    """创建分类日志器"""
    logger = logging.getLogger(name)
    logger.setLevel("INFO")

    # 文件 Handler
    file_handler = logging.FileHandler(
        os.path.join(LOG_DIR, filename),
        encoding="utf-8"
    )
    file_handler.setFormatter(logging.Formatter(LOG_FORMAT))
    logger.addHandler(file_handler)

    # 控制台 Handler
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setFormatter(logging.Formatter(LOG_FORMAT))
    logger.addHandler(console_handler)

    return logger


# 创建各分类日志器
logger = setup_logger("ai-wallpaper", "ai-wallpaper.log")
request_logger = setup_logger("ai-wallpaper.request", "request.log")  # 请求日志
sse_logger = setup_logger("ai-wallpaper.sse", "sse.log")              # SSE 日志
volcanic_logger = setup_logger("ai-wallpaper.volcanic", "volcanic.log")  # 火山引擎 API 日志

六、启动验证

6.1 启动脚本

#!/bin/bash
# start.sh - 启动脚本

echo "=== AI Wallpaper Server 启动 ==="

# 检查 Python 版本
python3 --version || { echo "Python3 未安装"; exit 1; }

# 激活虚拟环境
if [ -f "venv/bin/activate" ]; then
    source venv/bin/activate
fi

# 检查配置文件
python3 -c "from core.config import settings; print('配置加载成功')" || { echo "配置错误"; exit 1; }

# 启动服务
echo "启动服务：http://0.0.0.0:${PORT:-8080}"
uvicorn main:app --host ${HOST:-0.0.0.0} --port ${PORT:-8080} --log-level info

6.2 验证步骤

# 1. 健康检查
curl http://localhost:8080/health
# 输出: {"status":"ok","message":"Service is healthy"}

# 2. 服务信息
curl http://localhost:8080/
# 输出: {"service":"AI Wallpaper API","version":"1.0.0","protocol":"A2A / 鸿蒙 Agent 通信协议"}

# 3. A2A 初始化
curl -X POST http://localhost:8080/agent/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
# 输出: {"jsonrpc":"2.0","id":1,"result":{"version":"1.0","agentSessionId":"xxx","agentSessionTtl":604800}}

6.3 环境配置检查清单

## 环境搭建检查清单

### □ Python 环境
- [ ] Python 3.11+ 已安装
- [ ] 虚拟环境已创建并激活
- [ ] requirements.txt 所有依赖已安装
- [ ] pip freeze 确认依赖版本

### □ 配置文件
- [ ] .env 文件已创建
- [ ] VOLCANIC_API_KEY 已正确配置
- [ ] 模型名称已正确配置
- [ ] 其他可选配置已填写

### □ Docker 环境（可选）
- [ ] Docker 已安装
- [ ] docker-compose 已安装
- [ ] Dockerfile 构建成功
- [ ] docker-compose up 启动正常

### □ API 连通性
- [ ] 火山引擎 API 连通性测试通过
- [ ] A2A initialize 方法返回正常
- [ ] 健康检查端点正常

七、环境配置参考

不同环境下的关键配置对比如下：

7.1 运行环境对比

环境	Python 版本	部署方式	适用阶段
开发环境	3.11+	虚拟环境 + uvicorn	本地开发与调试
测试环境	3.11+	Docker Compose	集成测试
生产环境	3.11+	Docker + systemd	线上服务

7.2 依赖版本对比

依赖	开发版本	生产版本	说明
FastAPI	>=0.109.0	锁定版本	生产环境建议锁定
httpx	>=0.26.0	锁定版本	异步 HTTP 客户端
pydantic	>=2.5.3	锁定版本	数据验证

7.3 模型成本对比

模型	用途	成本	选型建议
LANGUAGE_MODEL	闲聊与提示词优化	中	需要创作能力
INTENT_MODEL	意图分类	低	轻量省钱
IMAGE_MODEL	文生图	高	按张计费

上表成本仅为参考，实际费用请以火山引擎官方计费页面为准。

建议：生产环境务必锁定依赖版本，并对 IMAGE_MODEL 的调用做好配额监控。

总结

本文详细介绍了"鸿蒙壁纸大师"项目的环境搭建全过程：

1. 项目初始化：目录结构、虚拟环境、依赖管理
2. 环境变量：.env 文件配置、Settings 类、配置验证
3. 火山引擎：API Key 获取、三种模型的选择策略
4. Docker 部署：Dockerfile 构建、Compose 编排、启动命令
5. 日志系统：多文件分类日志配置
6. 启动验证：启动脚本、验证步骤、检查清单

完成环境搭建后，下一篇文章将深入 API 认证与会话管理，介绍 A2A 协议的认证流程和会话管理机制。

---

如果这篇文章对你有帮助，欢迎点赞 👍、收藏 ⭐ 和关注 🎯！你的支持是我持续创作的动力！

相关资源

• Python 虚拟环境指南
• FastAPI 部署文档
• 火山引擎 - 快速入门
• 火山引擎 - 豆包大模型定价
• Docker 官方文档
• docker-compose 参考
• python-dotenv 文档
• 鸿蒙智能体开发实战系列 - 全部文章
• Python httpx 异步 HTTP 客户端