# 360看房系统 - 部署说明

> 本教程面向完全不懂代码的用户。只要按照步骤操作，就能把系统部署到服务器上。

---

## 一、你需要准备什么

### 1.1 一台服务器（电脑）

需要一台安装了 Ubuntu 24.04 系统的电脑（可以是实体机、云服务器、或者 Docker 容器）。

**最低配置：**
- CPU：2核以上
- 内存：4GB 以上
- 硬盘：50GB 以上
- 系统：Ubuntu 24.04 LTS

**推荐配置：**
- CPU：4核以上
- 内存：8GB 以上
- 硬盘：100GB 以上

### 1.2 一个 SSH 连接工具

你需要通过 SSH 远程连接到服务器。

- **Windows 用户**：下载 [PuTTY](https://www.putty.org/) 或使用 Windows Terminal
- **Mac 用户**：打开"终端"应用即可
- **Linux 用户**：打开"终端"应用即可

### 1.3 服务器信息

确保你知道以下信息：

| 项目 | 说明 | 示例 |
|------|------|------|
| 服务器IP地址 | 服务器的网络地址 | 192.168.1.100 |
| SSH端口 | 远程连接的端口号 | 22 |
| 用户名 | 登录服务器的账号 | ubuntu |
| 密码 | 登录服务器的密码 | your-password |

---

## 二、连接服务器

### Windows 用户

1. 打开 PuTTY
2. 在 "Host Name" 输入服务器IP地址
3. 在 "Port" 输入端口号（通常是22）
4. 点击 "Open" 按钮
5. 输入用户名和密码（输入密码时不会显示任何字符，这是正常的）

### Mac / Linux 用户

1. 打开"终端"应用
2. 输入以下命令（把中文部分替换成你的实际信息）：
   ```
   ssh -p 端口号 用户名@服务器IP地址
   ```
   例如：`ssh -p 22 ubuntu@192.168.1.100`
3. 按回车，输入密码

---

## 三、安装必要软件

连接服务器后，按照以下步骤操作。**每一行命令输入完后按回车键执行。**

### 3.1 更新系统

```bash
sudo apt-get update
```

### 3.2 安装 MySQL 数据库

```bash
sudo apt-get install -y mysql-server
```

安装完成后，设置数据库：

```bash
sudo mysql
```

然后依次输入以下 SQL 语句（每次输入完按回车）：

```sql
CREATE DATABASE fang360 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fang360'@'localhost' IDENTIFIED BY 'fang360';
GRANT ALL PRIVILEGES ON fang360.* TO 'fang360'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### 3.3 安装 Redis

```bash
sudo apt-get install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server
```

### 3.4 安装 Python

```bash
sudo apt-get install -y python3 python3-pip python3-venv
```

### 3.5 安装 Node.js

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

验证安装（看到版本号说明成功）：

```bash
node --version
npm --version
```

### 3.6 安装 Nginx

```bash
sudo apt-get install -y nginx
```

---

## 四、部署系统代码

### 4.1 创建项目目录

```bash
sudo mkdir -p /data/wwwroot/360_web
sudo chown -R $USER:$USER /data/wwwroot/360_web
cd /data/wwwroot/360_web
```

### 4.2 上传代码

将项目代码复制到服务器的 `/data/wwwroot/360_web/` 目录下。

**方法一：使用U盘或移动硬盘复制**
1. 将代码文件夹复制到U盘
2. 将U盘插入服务器
3. 将文件复制到 `/data/wwwroot/360_web/`

**方法二：使用 scp 命令从其他电脑复制**
在**你自己的电脑**上打开终端，执行：
```bash
scp -P SSH端口 -r /你本地电脑上的代码路径/* 用户名@服务器IP:/data/wwwroot/360_web/
```

代码结构应该包含三个文件夹：
```
/data/wwwroot/360_web/
├── backend/        # 后端代码
├── frontend/       # 前端代码
└── ai-worker/      # AI分析代码
```

---

## 五、配置并启动后端

### 5.1 安装 Python 依赖

```bash
cd /data/wwwroot/360_web/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 5.2 创建配置文件

```bash
cat > .env << 'EOF'
DATABASE_URL=mysql+pymysql://fang360:teJRrcWmpNwFTnmS@localhost:3306/fang360?charset=utf8mb4
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=18
JWT_SECRET=gRZNEvbyf6U4WNp3rCcNQ3G0dMCX8qhb
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440
UPLOAD_DIR=./uploads
EOF
```

> **重要：** 请把 `请修改为你的随机密码至少32个字符` 替换成一个你自己想的随机密码。这个密码用于加密用户登录信息。

### 5.3 初始化数据库

```bash
source venv/bin/activate
alembic upgrade head
python3 -m app.seed
```

如果 alembic 命令报错，可以手动创建表：

```bash
python3 -c "
from app.database import engine, Base
from app.models import *
Base.metadata.create_all(bind=engine)
print('数据库创建成功')
"
```

### 5.4 创建上传文件夹

```bash
mkdir -p uploads
```

### 5.5 启动后端服务

```bash
source venv/bin/activate
nohup uvicorn app.main:app --host 0.0.0.0 --port 8000 > /tmp/backend.log 2>&1 &
```

### 5.6 验证后端是否启动成功

```bash
curl http://localhost:8000/health
```

如果看到 `{"status":"ok","service":"360 House Tour API"}`，说明后端启动成功。

---

## 六、配置并启动前端

### 6.1 安装前端依赖

```bash
cd /data/wwwroot/360_web/frontend
npm install
```

### 6.2 创建前端配置文件

```bash
cat > .env.local << 'EOF'
NEXT_PUBLIC_API_URL=http://localhost:8000/api
EOF
```

### 6.3 构建前端

```bash
npm run build
```

### 6.4 启动前端服务

```bash
nohup npx next start -p 3000 > /tmp/frontend.log 2>&1 &
```

---

## 七、配置 Nginx（统一入口）

### 7.1 创建 Nginx 配置文件

```bash
sudo tee /etc/nginx/sites-available/fang360 << 'EOF'
server {
    listen 80;
    server_name _;
    client_max_body_size 100M;

    # 前端页面
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }

    # 后端接口
    location /api/ {
        proxy_pass http://127.0.0.1:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 上传的图片
    location /uploads/ {
        alias /data/wwwroot/360_web/backend/uploads/;
    }
}
EOF
```

### 7.2 启用配置

```bash
sudo ln -sf /etc/nginx/sites-available/fang360 /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx
```

---

## 八、配置 AI 分析服务（可选）

如果暂时不需要 AI 自动分析功能，可以跳过这一步。

### 8.1 安装 AI 依赖

```bash
cd /data/wwwroot/360_web/ai-worker
pip install -r requirements.txt
```

### 8.2 启动 AI 服务

```bash
cd /data/wwwroot/360_web/ai-worker
source ../backend/venv/bin/activate
nohup celery -A celery_app worker --loglevel=info --concurrency=2 > /tmp/worker.log 2>&1 &
```

---

## 九、验证部署

在浏览器中打开：`http://你的服务器IP地址`

你应该看到：
1. 登录页面
2. 输入测试账号：`admin@fang360.com`，密码：`admin123`
3. 登录后进入管理后台
4. 可以创建房源、上传360全景图、编辑热点

---

## 十、设置开机自启

为了让系统在服务器重启后自动运行，执行以下命令：

### 10.1 后端自启

```bash
sudo tee /etc/systemd/system/fang360-backend.service << 'EOF'
[Unit]
Description=360 House Tour Backend
After=network.target mysql.service redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/data/wwwroot/360_web/backend
Environment="PATH=/data/wwwroot/360_web/backend/venv/bin"
ExecStart=/data/wwwroot/360_web/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable fang360-backend
sudo systemctl start fang360-backend
```

### 10.2 前端自启

```bash
sudo tee /etc/systemd/system/fang360-frontend.service << 'EOF'
[Unit]
Description=360 House Tour Frontend
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/data/wwwroot/360_web/frontend
ExecStart=/usr/bin/npx next start -p 3000
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable fang360-frontend
sudo systemctl start fang360-frontend
```

---

## 十一、常见问题

### Q1: 访问页面显示"无法连接"

**检查步骤：**
1. 确认服务器防火墙是否开放了 80 端口
2. 确认 Nginx 是否启动：`sudo systemctl status nginx`
3. 确认后端是否启动：`curl http://localhost:8000/health`

### Q2: 登录时提示"无效的登录凭证"

**解决方法：**
重新运行种子数据脚本创建测试账号：
```bash
cd /data/wwwroot/360_web/backend
source venv/bin/activate
python3 -m app.seed
```

### Q3: 上传图片失败

**检查步骤：**
1. 确认 uploads 文件夹存在且有写入权限
2. 确认图片是 360 全景格式（宽高比必须是 2:1）
3. 确认图片大小不超过 50MB

### Q4: 如何修改为使用外网访问

如果你有域名，修改 Nginx 配置中的 `server_name`：
```bash
sudo nano /etc/nginx/sites-available/fang360
```
将 `server_name _;` 改为 `server_name 你的域名.com;`
然后重启 Nginx：`sudo systemctl restart nginx`

### Q5: 如何更换测试管理员密码

启动后端后，访问 `http://你的服务器IP/login`，使用注册功能创建一个新账号，然后将新账号设置为管理员。

---

## 十二、日常维护

### 查看后端日志
```bash
tail -f /tmp/backend.log
```

### 查看前端日志
```bash
tail -f /tmp/frontend.log
```

### 重启后端
```bash
sudo systemctl restart fang360-backend
```

### 重启前端
```bash
sudo systemctl restart fang360-frontend
```

### 备份数据库
```bash
mysqldump -u fang360 -pfang360 fang360 > /tmp/backup_$(date +%Y%m%d).sql
```

### 恢复数据库
```bash
mysql -u fang360 -pfang360 fang360 < /tmp/backup_20260529.sql
```

---

> **技术支持：** 如遇到问题，请将错误截图和日志内容发送给开发团队。