ozon-seller-kit/docs/deployment.md

Ozon Seller Kit：部署与启动

本地一体服务：FastAPI 托管 web/ 静态页，并提供 /api/*。默认只监听本机，适合个人 Mac 开发与日常使用。

---

1. 环境要求

项	说明
系统	macOS（start.command 为 zsh；其他系统用手动启动即可）
Python	3.10+（需已安装 python3）
网络	生成俄文文案时需能访问 DeepSeek API
端口	默认 8000，请确保未被占用

---

2. 获取代码与进入目录

cd /path/to/ozon-seller-kit

项目结构（与启动相关）：

ozon-seller-kit/
├── main.py              # FastAPI 入口
├── start.command        # macOS 一键启动
├── requirements.txt
├── .env.example         # 环境变量模板
├── .env                 # 本地密钥（勿提交）
├── config/
│   ├── settings.py
│   └── models.yaml      # 可选模型清单
└── web/                 # 前端静态页

---

3. 配置环境变量

3.1 创建 .env

首次启动若没有 .env，start.command 会从 .env.example 复制一份并退出，提示你填密钥。也可手动：

cp .env.example .env

3.2 必填项

编辑 .env：

DEEPSEEK_API_KEY=sk-你的密钥

没有有效 DEEPSEEK_API_KEY 时，页面可打开，但「俄文文案」生成会失败。

3.3 可选项

HOST=127.0.0.1
PORT=8000
# 前后端不同源时再填，逗号分隔；同源挂载可留空
CORS_ORIGINS=

说明：

• HOST / PORT 由 config/settings.py 读取；当前 start.command 写死为 127.0.0.1:8000。若要改端口，需同步改启动命令或脚本。
• 以后若在 config/models.yaml 中接入其他厂商，按其中的 api_key_env 在 .env 增加对应变量（例如 OPENAI_API_KEY）。

3.4 模型清单（可选）

config/models.yaml 控制页面模型下拉与默认模型，可直接改 default 或增删 models 条目。密钥只通过 api_key_env 引用环境变量名，不要把 Key 写进 yaml。

开发模式下改 yaml 会热重载（见下方启动参数 --reload-include '*.yaml'）。

---

4. 启动方式

方式 A：一键启动（推荐，macOS）

双击 start.command，或在终端执行：

chmod +x start.command   # 仅首次需要
./start.command

脚本会：

1. 若不存在 .venv → 创建虚拟环境并 pip install -r requirements.txt
2. 若不存在 .env → 从 .env.example 复制后退出，请填 Key 后再次启动
3. 启动 Uvicorn：http://127.0.0.1:8000

停止：终端里 Ctrl+C；若是双击打开的窗口，停止后按回车关闭。

方式 B：手动启动

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 确保已配置 .env
uvicorn main:app --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000

生产或长时间挂机可不加 --reload：

uvicorn main:app --host 127.0.0.1 --port 8000

---

5. 访问与自检

地址	用途
http://127.0.0.1:8000/ozonSeller.html	主页面
http://127.0.0.1:8000/api/health	健康检查，应返回 {"status":"ok"}
http://127.0.0.1:8000/api/ai/models	模型列表（需服务已启动）
http://127.0.0.1:8000/docs	FastAPI 自动文档（Swagger）

建议自检顺序：

1. 打开健康检查，确认服务在跑。
2. 打开主页面，确认模型下拉有选项。
3. 在「俄文文案」区粘贴一段采买信息，点生成，确认能返回标题/描述/标签。

---

6. 主要 API（当前）

方法	路径	说明
GET	/api/health	健康检查
GET	/api/ai/models	可选模型列表
POST	/api/ai/copy	中文采买信息 → 俄文文案 + 中文对照

预留路由（尚未实现业务）：/api/image/*、/api/ozon/*。

文案能力与接口约定详见 ai-copy-backend-plan.md。

---

7. 常见问题

端口被占用

报错类似 Address already in use：换端口启动，或结束占用进程。

lsof -i :8000
uvicorn main:app --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8001

换端口后页面地址改为对应端口。

.env 已填 Key，文案仍失败

• 确认 Key 无多余空格、引号。
• 确认当前进程是从项目根目录启动（.env 在仓库根目录加载）。
• 改 .env 后需重启服务（环境变量不会像 yaml 那样热更新）。
• 检查本机能否访问 https://api.deepseek.com。

双击 start.command 一闪而过 / 无权限

chmod +x start.command

若仍被 macOS 拦截，可在终端执行 ./start.command，或在「系统设置 → 隐私与安全性」中允许。

依赖安装失败

先确认 python3 可用，再手动：

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

只想看静态页、不用 AI

仍建议通过本服务打开页面（同源），避免 file:// 下部分能力受限。没有 Key 时计价、登记、浏览器水印等本地功能仍可使用。

---

8. 安全注意

• .env 含密钥，已在 .gitignore 中忽略，不要提交到 Git。
• 默认绑定 127.0.0.1，仅本机可访问。若改为 0.0.0.0 对外暴露，请自行做好网络隔离与密钥保护；本仓库当前按本机工具设计，未做登录鉴权。

---

9. 日常开发建议

source .venv/bin/activate
uvicorn main:app --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000

• 改 Python / yaml：热重载后自动生效（.env 除外，需重启）。
• 改 web/ 下 HTML/JS/CSS：刷新浏览器即可。