R524809
217 lines
6.1 KiB
Markdown
217 lines
6.1 KiB
Markdown
# Ozon Seller Kit：部署与启动
|
||
|
||
本地一体服务：FastAPI 托管 `web/` 静态页，并提供 `/api/*`。默认只监听本机，适合个人 Mac 开发与日常使用。
|
||
|
||
---
|
||
|
||
## 1. 环境要求
|
||
|
||
| 项 | 说明 |
|
||
| --- | --- |
|
||
| 系统 | macOS（`start.command` 为 zsh；其他系统用手动启动即可） |
|
||
| Python | 3.10+（需已安装 `python3`） |
|
||
| 网络 | 生成俄文文案时需能访问 DeepSeek API |
|
||
| 端口 | 默认 `8000`，请确保未被占用 |
|
||
|
||
---
|
||
|
||
## 2. 获取代码与进入目录
|
||
|
||
```bash
|
||
cd /path/to/ozon-seller-kit
|
||
```
|
||
|
||
项目结构（与启动相关）：
|
||
|
||
```
|
||
ozon-seller-kit/
|
||
├── start.command # macOS 一键启动
|
||
├── .env.example # 环境变量模板
|
||
├── .env # 本地密钥（勿提交，位于仓库根）
|
||
├── server/ # ④ 后端
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── requirements.txt
|
||
│ └── config/
|
||
│ ├── settings.py
|
||
│ └── models.yaml # 可选模型清单
|
||
└── web/ # ① 工具台 v1 静态页
|
||
```
|
||
|
||
> 后端在 `server/` 下，但 `.env` 在**仓库根**，由各部分共用。启动时工作目录保持仓库根，靠 `--app-dir server` 定位应用。
|
||
|
||
---
|
||
|
||
## 3. 配置环境变量
|
||
|
||
### 3.1 创建 `.env`
|
||
|
||
首次启动若没有 `.env`，`start.command` 会从 `.env.example` 复制一份并退出，提示你填密钥。也可手动：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 3.2 必填项
|
||
|
||
编辑 `.env`：
|
||
|
||
```env
|
||
DEEPSEEK_API_KEY=sk-你的密钥
|
||
```
|
||
|
||
没有有效 `DEEPSEEK_API_KEY` 时，页面可打开，但「俄文文案」生成会失败。
|
||
|
||
### 3.3 可选项
|
||
|
||
```env
|
||
HOST=127.0.0.1
|
||
PORT=8000
|
||
# 前后端不同源时再填，逗号分隔；同源挂载可留空
|
||
CORS_ORIGINS=
|
||
```
|
||
|
||
说明：
|
||
|
||
- `HOST` / `PORT` 由 `server/config/settings.py` 读取；当前 `start.command` 写死为 `127.0.0.1:8000`。若要改端口，需同步改启动命令或脚本。
|
||
- 以后若在 `server/config/models.yaml` 中接入其他厂商，按其中的 `api_key_env` 在 `.env` 增加对应变量（例如 `OPENAI_API_KEY`）。
|
||
|
||
### 3.4 模型清单（可选）
|
||
|
||
`server/config/models.yaml` 控制页面模型下拉与默认模型，可直接改 `default` 或增删 `models` 条目。密钥只通过 `api_key_env` 引用环境变量名，不要把 Key 写进 yaml。
|
||
|
||
开发模式下改 yaml 会热重载（见下方启动参数 `--reload-include '*.yaml'`）。
|
||
|
||
---
|
||
|
||
## 4. 启动方式
|
||
|
||
### 方式 A：一键启动（推荐，macOS）
|
||
|
||
双击 `start.command`，或在终端执行：
|
||
|
||
```bash
|
||
chmod +x start.command # 仅首次需要
|
||
./start.command
|
||
```
|
||
|
||
脚本会：
|
||
|
||
1. 若不存在 `.venv` → 创建虚拟环境并 `pip install -r server/requirements.txt`
|
||
2. 若不存在 `.env` → 从 `.env.example` 复制后退出，请填 Key 后再次启动
|
||
3. 启动 Uvicorn：`http://127.0.0.1:8000`
|
||
|
||
停止：终端里 `Ctrl+C`；若是双击打开的窗口，停止后按回车关闭。
|
||
|
||
### 方式 B：手动启动
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r server/requirements.txt
|
||
|
||
# 确保已配置 .env（在仓库根）。始终在仓库根执行，靠 --app-dir 定位应用
|
||
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
生产或长时间挂机可不加 `--reload`：
|
||
|
||
```bash
|
||
uvicorn main:app --app-dir server --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`](./ai-copy-backend-plan.md)。
|
||
|
||
---
|
||
|
||
## 7. 常见问题
|
||
|
||
### 端口被占用
|
||
|
||
报错类似 `Address already in use`：换端口启动，或结束占用进程。
|
||
|
||
```bash
|
||
lsof -i :8000
|
||
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8001
|
||
```
|
||
|
||
换端口后页面地址改为对应端口。
|
||
|
||
### `.env` 已填 Key，文案仍失败
|
||
|
||
- 确认 Key 无多余空格、引号。
|
||
- 确认当前进程是从项目根目录启动（`.env` 在仓库根目录加载）。
|
||
- 改 `.env` 后需重启服务（环境变量不会像 yaml 那样热更新）。
|
||
- 检查本机能否访问 `https://api.deepseek.com`。
|
||
|
||
### 双击 `start.command` 一闪而过 / 无权限
|
||
|
||
```bash
|
||
chmod +x start.command
|
||
```
|
||
|
||
若仍被 macOS 拦截，可在终端执行 `./start.command`，或在「系统设置 → 隐私与安全性」中允许。
|
||
|
||
### 依赖安装失败
|
||
|
||
先确认 `python3` 可用，再手动：
|
||
|
||
```bash
|
||
rm -rf .venv
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -U pip
|
||
pip install -r server/requirements.txt
|
||
```
|
||
|
||
### 只想看静态页、不用 AI
|
||
|
||
仍建议通过本服务打开页面（同源），避免 `file://` 下部分能力受限。没有 Key 时计价、登记、浏览器水印等本地功能仍可使用。
|
||
|
||
---
|
||
|
||
## 8. 安全注意
|
||
|
||
- `.env` 含密钥，已在 `.gitignore` 中忽略，**不要提交到 Git**。
|
||
- 默认绑定 `127.0.0.1`，仅本机可访问。若改为 `0.0.0.0` 对外暴露，请自行做好网络隔离与密钥保护；本仓库当前按本机工具设计，未做登录鉴权。
|
||
|
||
---
|
||
|
||
## 9. 日常开发建议
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
uvicorn main:app --app-dir server --reload --reload-include '*.yaml' --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
- 改 Python / yaml：热重载后自动生效（`.env` 除外，需重启）。
|
||
- 改 `web/` 下 HTML/JS/CSS：刷新浏览器即可。
|