geMoldInsight/docs/deployment/DEPLOY_PORT.md

# 部署时端口配置说明

## 生产环境部署端口配置

本项目现在使用统一的端口配置文件 `.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` 作为模板