Merge branch 'main' of http://jymj.top:10001/cjw/geMoldInsight

2026-02-14 17:15:22 +08:00
parent 2c5d840117 da4a9de4a3
commit e63d81f0aa
3 changed files with 469 additions and 0 deletions
@@ -0,0 +1,170 @@
+# 部署时端口配置说明
+
+## 生产环境部署端口配置
+
+本项目现在使用统一的端口配置文件 `.env`，部署时需要相应调整配置。
+
+### Gunicorn 启动配置
+
+**推荐方式（使用 .env 配置）：**
+
+```bash
+# 创建启动脚本
+cat > start_production.sh << 'EOF'
+#!/bin/bash
+cd /opt/moldinsight/moldinsight_project
+source venv/bin/activate
+
+# 从 .env 读取端口配置
+if [ -f .env ]; then
+    PORT=$(grep '^PORT=' .env | cut -d'=' -f2)
+else
+    PORT=8000
+fi
+
+# 启动服务
+gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:${PORT}
+EOF
+
+chmod +x start_production.sh
+./start_production.sh
+```
+
+### systemd 服务配置
+
+创建 `/etc/systemd/system/moldinsight.service`：
+
+```ini
+[Unit]
+Description=MoldInsight Geometry Analysis Service
+After=network.target postgresql.service
+
+[Service]
+Type=simple
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/moldinsight/moldinsight_project
+Environment=PATH=/opt/moldinsight/moldinsight_project/venv/bin
+Environment="PORT=8000"
+ExecStart=/opt/moldinsight/moldinsight_project/venv/bin/gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:${PORT}
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**重要：** 在 `[Service]` 部分添加 `Environment="PORT=8000"`，或在 `.env` 文件中配置 `PORT=8000`。
+
+### Nginx 反向代理配置
+
+```nginx
+upstream moldinsight_backend {
+    server 127.0.0.1:8000;  # 对应 .env 中的 PORT
+}
+
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://moldinsight_backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /static {
+        alias /opt/moldinsight/moldinsight_project/static;
+    }
+
+    location /html_output {
+        alias /opt/moldinsight/moldinsight_project/html_output;
+    }
+}
+```
+
+### Docker 部署
+
+Docker 部署自动从 `.env` 读取配置，无需额外设置：
+
+```bash
+# .env 文件配置
+PORT=8000          # 容器内端口
+HOST_PORT=8080     # 宿主机端口
+
+# 启动
+docker-compose up -d
+```
+
+### 修改生产环境端口
+
+1. **编辑 .env 文件**
+   ```bash
+   PORT=9000  # 修改应用端口
+   ```
+
+2. **重启服务**
+   ```bash
+   # systemd
+   sudo systemctl restart moldinsight
+
+   # Docker
+   docker-compose down && docker-compose up -d
+
+   # 手动启动
+   ./start_production.sh
+   ```
+
+3. **更新 Nginx 配置（如果使用）**
+   ```nginx
+   upstream moldinsight_backend {
+       server 127.0.0.1:9000;  # 更新为新端口
+   }
+   ```
+   ```bash
+   sudo nginx -t && sudo nginx -s reload
+   ```
+
+### 防火墙配置
+
+如果修改了端口，需要更新防火墙规则：
+
+```bash
+# UFW (Ubuntu/Debian)
+sudo ufw allow 9000/tcp
+sudo ufw delete allow 8000/tcp  # 删除旧端口
+
+# firewall-cmd (CentOS/RHEL)
+sudo firewall-cmd --permanent --add-port=9000/tcp
+sudo firewall-cmd --permanent --remove-port=8000/tcp
+sudo firewall-cmd --reload
+```
+
+### 健康检查
+
+修改端口后，更新健康检查命令：
+
+```bash
+# 检查服务状态
+curl http://localhost:9000/health
+curl http://your-domain.com/health
+```
+
+## 快速参考
+
+| 部署方式 | 端口配置位置 | 重启命令 |
+|---------|------------|---------|
+| 直接运行 | `.env` 中的 `PORT` | Ctrl+C 后重新运行 |
+| Gunicorn | `.env` 中的 `PORT` | `systemctl restart moldinsight` |
+| Docker | `.env` 中的 `PORT` 和 `HOST_PORT` | `docker-compose restart` |
+| Nginx代理 | Nginx配置中的 `proxy_pass` | `nginx -s reload` |
+
+## 注意事项
+
+⚠️ **重要：**
+1. 所有端口配置统一在 `.env` 文件中管理
+2. 修改端口后需要同步更新相关配置（Nginx、防火墙等）
+3. 确保新端口没有被其他服务占用
+4. 生产环境建议使用 Nginx 反向代理，对外提供 80/443 端口
+5. .env 文件不应提交到版本控制系统，使用 `.env.example` 作为模板
@@ -0,0 +1,107 @@
+# 端口配置说明
+
+## ⚠️ 重要提示
+
+本项目现在采用**统一端口配置管理**，所有端口配置集中在一个地方：
+
+**唯一修改端口的地方：** `.env` 文件中的端口配置部分
+
+## 配置说明
+
+编辑项目根目录下的 `.env` 文件：
+
+```bash
+# ================================
+# 端口配置 - 唯一修改端口的地方
+# ================================
+# 应用端口（容器内端口）
+PORT=8000
+# Docker映射到宿主机的端口（docker-compose使用）
+HOST_PORT=10001
+# ================================
+```
+
+### 端口含义
+
+| 变量 | 用途 | 默认值 | 说明 |
+|------|------|--------|------|
+| `PORT` | 应用监听端口 | 8000 | FastAPI/Uvicorn 服务监听的端口 |
+| `HOST_PORT` | 宿主机映射端口 | 10001 | Docker Compose 映射到宿主机的端口 |
+
+### 使用场景
+
+#### 1. 本地直接运行（Python）
+```bash
+python src/main.py
+```
+服务将在 `http://localhost:8000` 启动（使用 `PORT` 配置）
+
+#### 2. Docker Compose 运行
+```bash
+docker-compose up
+```
+服务将在 `http://localhost:10001` 访问（使用 `HOST_PORT` 配置）
+容器内部使用 `PORT` 配置的端口（8000）
+
+#### 3. 修改端口
+
+**场景A：只想修改外部访问端口（Docker）**
+```bash
+# .env 文件
+PORT=8000          # 容器内不变
+HOST_PORT=8080     # 宿主机改为8080
+```
+访问地址：`http://localhost:8080`
+
+**场景B：修改应用端口（容器内/本地运行）**
+```bash
+# .env 文件
+PORT=9000          # 应用改为9000
+HOST_PORT=10001    # 宿主机映射到10001
+```
+- 本地运行：`http://localhost:9000`
+- Docker运行：`http://localhost:10001` （映射到容器内9000）
+
+**场景C：同时修改两个端口**
+```bash
+# .env 文件
+PORT=9000
+HOST_PORT=9000
+```
+- 本地运行：`http://localhost:9000`
+- Docker运行：`http://localhost:9000`
+
+## 配置文件说明
+
+### 配置读取优先级
+
+1. **`config/settings.py`** - 从 `.env` 读取 `PORT` 和 `HOST`
+2. **`src/main.py`** - 从 `settings` 获取端口配置
+3. **`docker-compose.yml`** - 从 `.env` 读取 `HOST_PORT` 和 `PORT`
+
+### 相关文件
+
+- **`.env`** - ⭐ 唯一需要修改的配置文件
+- **`config/settings.py`** - 配置读取逻辑（无需修改）
+- **`src/main.py`** - 使用配置启动服务（无需修改）
+- **`docker-compose.yml`** - Docker端口映射（自动读取 `.env`）
+- **`start.sh` / `start_fixed.sh`** - 启动脚本（自动读取 `.env`）
+
+## 常见问题
+
+### Q: 为什么 Docker 宿主机端口和应用端口分开配置？
+A: 这样可以灵活调整容器端口而不影响外部访问，也避免端口冲突。
+
+### Q: 修改后需要重启吗？
+A: 是的，修改 `.env` 后需要重启服务才能生效：
+- 本地运行：Ctrl+C 停止后重新 `python src/main.py`
+- Docker: `docker-compose down && docker-compose up`
+
+### Q: 如何避免端口冲突？
+A: 确保 `HOST_PORT` 不与其他服务冲突，可以使用 `netstat -an | grep <端口>` 检查端口占用情况。
+
+### Q: 可以使用 80 端口吗？
+A: 可以，但需要管理员权限：
+- Linux/Mac: 使用 sudo
+- Docker: 需要容器有足够权限
+- 生产环境建议使用反向代理（如 Nginx）
@@ -0,0 +1,192 @@
+# 端口配置重构总结
+
+## 修改内容
+
+本次重构将项目的端口配置统一到 `.env` 文件中，确保整个项目只有一个地方需要修改端口。
+
+## 修改的文件
+
+### 1. ⭐ `.env` - 唯一配置入口
+**变更：** 添加了统一的端口配置区域
+```bash
+# ================================
+# 端口配置 - 唯一修改端口的地方
+# ================================
+# 应用端口（容器内端口）
+PORT=8000
+# Docker映射到宿主机的端口（docker-compose使用）
+HOST_PORT=10001
+# ================================
+```
+
+### 2. `src/main.py`
+**变更：** 从硬编码的环境变量读取改为从 `config.settings` 读取
+```python
+# 修改前
+host = os.getenv('HOST', '0.0.0.0')
+port = int(os.getenv('PORT', '8000'))
+
+# 修改后
+from config.settings import settings
+# ...
+host=settings.HOST,
+port=settings.PORT
+```
+
+### 3. `docker-compose.yml`
+**变更：** 端口映射从硬编码改为从环境变量读取
+```yaml
+# 修改前
+ports:
+  - "10001:8000"
+environment:
+  - PORT=8000
+
+# 修改后
+ports:
+  - "${HOST_PORT:-10001}:${CONTAINER_PORT:-8000}"
+environment:
+  - HOST=${HOST:-0.0.0.0}
+  - PORT=${CONTAINER_PORT:-8000}
+```
+
+### 4. `start.sh` 和 `start_fixed.sh`
+**变更：** 自动从 `.env` 读取端口并显示正确的访问地址
+```bash
+# 添加
+PORT=$(grep '^PORT=' .env 2>/dev/null | cut -d'=' -f2 || echo '8000')
+echo "🌐 服务将在 http://localhost:${PORT} 启动"
+```
+
+### 5. `README.md`
+**变更：** 更新访问说明，提示端口配置位置
+
+### 6. 新增文件
+- `.env.example` - 配置文件模板
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署时端口配置指南
+
+## 配置读取流程
+
+```
+.env 文件
+    ↓
+config/settings.py (读取 PORT 和 HOST)
+    ↓
+src/main.py (使用 settings.PORT)
+    ↓
+uvicorn 启动服务
+```
+
+Docker 部署流程：
+```
+.env 文件
+    ↓
+docker-compose.yml (读取 HOST_PORT 和 PORT)
+    ↓
+容器映射和内部启动
+```
+
+## 如何修改端口
+
+### 方法 1：修改应用端口
+```bash
+# 编辑 .env
+PORT=9000  # 修改此行
+```
+- 本地运行：`http://localhost:9000`
+- Docker运行：需同时修改 `HOST_PORT=9000`
+
+### 方法 2：修改 Docker 外部访问端口
+```bash
+# 编辑 .env
+HOST_PORT=8080  # 修改此行（PORT 保持不变）
+```
+- Docker运行：`http://localhost:8080`
+- 容器内仍使用 PORT 配置的端口
+
+## 测试验证
+
+### 测试 1：本地运行
+```bash
+# 修改 .env 中的 PORT
+PORT=9999
+
+# 启动服务
+python src/main.py
+
+# 验证
+curl http://localhost:9999/health
+```
+
+### 测试 2：Docker 运行
+```bash
+# 修改 .env
+PORT=8000
+HOST_PORT=9999
+
+# 启动容器
+docker-compose up -d
+
+# 验证
+curl http://localhost:9999/health
+```
+
+### 测试 3：启动脚本
+```bash
+# 修改 .env
+PORT=8888
+
+# 运行启动脚本
+./start.sh
+
+# 检查输出是否显示正确的端口
+```
+
+## 注意事项
+
+1. ✅ 所有端口配置集中在 `.env` 文件
+2. ✅ 无需修改代码文件即可更改端口
+3. ✅ 支持本地运行和 Docker 部署两种场景
+4. ✅ 提供了详细的配置文档
+5. ⚠️ 修改端口后需要重启服务
+6. ⚠️ Docker 部署时需要同时考虑容器内外端口
+7. ⚠️ 确保新端口没有被占用
+
+## 文件清单
+
+### 修改的文件
+- `.env` - 添加端口配置区域
+- `src/main.py` - 统一使用 settings 配置
+- `docker-compose.yml` - 支持环境变量配置端口
+- `start.sh` - 自动读取和显示端口
+- `start_fixed.sh` - 自动读取和显示端口
+- `README.md` - 更新访问说明
+
+### 新增的文件
+- `.env.example` - 配置模板
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署配置指南
+- `PORT_REFACTOR_SUMMARY.md` - 本文档
+
+## 回滚方案
+
+如果需要回滚，按以下步骤操作：
+
+```bash
+git checkout -- src/main.py
+git checkout -- docker-compose.yml
+git checkout -- start.sh start_fixed.sh
+git checkout -- .env
+git checkout -- README.md
+
+# 删除新增文件
+rm .env.example PORT_CONFIG.md DEPLOY_PORT.md PORT_REFACTOR_SUMMARY.md
+```
+
+## 联系支持
+
+如有问题，请查看：
+- `PORT_CONFIG.md` - 端口配置详细说明
+- `DEPLOY_PORT.md` - 部署配置指南
+- `.env.example` - 配置示例