From 3a8ec576ee1ca4d1b1b76807a8232fbc4cb0c3c0 Mon Sep 17 00:00:00 2001
From: empty <let5sne.mac@gmail.com>
Date: Sat, 10 Jan 2026 16:13:23 +0800
Subject: [PATCH] docs: Add port configuration guide

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/port-configuration.md | 54 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/port-configuration.md

diff --git a/docs/port-configuration.md b/docs/port-configuration.md
new file mode 100644
index 0000000..ed36b7b
--- /dev/null
+++ b/docs/port-configuration.md
@@ -0,0 +1,54 @@
+# 端口配置说明
+
+## 默认端口
+
+| 服务 | 默认端口 | 说明 |
+|------|---------|------|
+| FastAPI 后端 | 8000 | API 服务和文档 |
+| Next.js 编辑器 | 3000 | 时间轴编辑器 |
+| Streamlit Web UI | 8501 | Web 界面 |
+
+## 自定义端口
+
+### 方式 1: 环境变量（临时）
+
+```bash
+# 自定义所有端口
+API_PORT=8080 EDITOR_PORT=3001 WEB_PORT=8502 ./dev.sh
+
+# 只自定义部分端口
+API_PORT=8080 ./dev.sh
+```
+
+### 方式 2: .env 文件（持久）
+
+1. 复制示例配置文件：
+   ```bash
+   cp .env.example .env
+   ```
+
+2. 编辑 `.env` 文件，修改端口：
+   ```bash
+   API_PORT=8080
+   EDITOR_PORT=3001
+   WEB_PORT=8502
+   ```
+
+3. 启动服务：
+   ```bash
+   ./dev.sh
+   ```
+
+## 注意事项
+
+1. **端口冲突**：确保选择的端口没有被其他程序占用
+2. **防火墙**：如需外部访问，请配置防火墙规则
+3. **前端重建**：修改端口后，Next.js 前端会自动重建（首次启动较慢）
+
+## 验证端口配置
+
+启动后访问以下地址确认服务正常：
+
+- API 文档: `http://localhost:{API_PORT}/docs`
+- 编辑器: `http://localhost:{EDITOR_PORT}`
+- Web UI: `http://localhost:{WEB_PORT}`