# wx.xiangyuan.hengtaisftech.com Apache 配置指南（实战修正版）

> **项目路径**：`/home/ubuntu/project/xiangyuan/xiangyuan_clouldServer`  
> **访问域名**：`https://wx.xiangyuan.hengtaisftech.com/`  
> **服务器 IP**：`82.156.120.191`  
> **Apache 运行用户**：`www-data`

---

## ⚠️ 重要：配置顺序不能错

根据实际踩坑经验，**必须按以下顺序执行**，否则 Apache 会启动失败：

```
1. 目录权限 → 2. 配置 DNS → 3. 创建并启用 HTTP(80) → 
4. 申请 SSL 证书 → 5. 创建并启用 HTTPS(443) → 6. 验证
```

**致命错误**：在证书申请成功之前，**不要启用 HTTPS 配置**，否则 Apache 会因找不到证书文件而无法启动。

---

## 第一步：设置目录权限

### 1.1 确保路径上的每个目录 www-data 都能进入

```bash
sudo chmod o+rx /home/ubuntu
sudo chmod o+rx /home/ubuntu/project
sudo chmod o+rx /home/ubuntu/project/xiangyuan
```

### 1.2 设置项目目录用户和权限

```bash
# 改为 ubuntu 用户 + www-data 组
sudo chown -R ubuntu:www-data /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

# 目录 755，文件 644
sudo chmod -R u+rwX,go+rX,go-w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

# 如果 PHP 需要写入某些子目录（如 uploads、cache、logs），单独开放：
# sudo chmod -R g+w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer/目标目录
```

### 1.3 验证权限

```bash
namei -l /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer
```

确保路径上每一级都有 `x` 权限（可进入）。

---

## 第二步：配置域名 DNS（必须先做）

> ⚠️ **这是最容易被忽略的一步，但必须先完成。**  
> Let's Encrypt 申请证书时，会向该域名发起验证请求。如果域名解析不到服务器 IP，证书申请会直接失败。

### 2.1 确定你的域名管理平台

找到管理 `hengtaisftech.com` 这个域名的平台。常见的有：

| 服务商 | 进入路径 |
|--------|----------|
| **阿里云** | 登录阿里云控制台 → 域名 → 域名列表 → 找到 `hengtaisftech.com` → 解析设置 |
| **腾讯云** | 登录腾讯云控制台 → 域名注册 → 我的域名 → 找到 `hengtaisftech.com` → 解析 |
| **Cloudflare** | 登录 Cloudflare → 选择 `hengtaisftech.com` → DNS → Records |
| **GoDaddy** | 登录 GoDaddy → My Products → Domains → 找到 `hengtaisftech.com` → Manage DNS |
| **华为云/其他** | 找到域名管理页面，进入 DNS 解析/记录管理 |

> 如果你不知道域名在哪里管理，可以在 [whois.domaintools.com](https://whois.domaintools.com) 查询 `hengtaisftech.com` 的 Registrar（注册商）。

### 2.2 添加 A 记录

在解析设置页面，**添加一条新的解析记录**，填写内容如下：

| 字段 | 填写内容 | 说明 |
|------|----------|------|
| **记录类型** | `A` | 将域名指向 IPv4 地址 |
| **主机记录** | `wx.xiangyuan` | 子域名前缀，最终构成 `wx.xiangyuan.hengtaisftech.com` |
| **记录值** | `82.156.120.191` | 你的服务器公网 IP |
| **TTL** | `600` 或默认 | 缓存时间，单位秒。默认 10 分钟即可 |
| **线路类型** | 默认 | 一般保持默认 |

#### 不同服务商的填写示例

**阿里云 / 腾讯云：**
```
记录类型: A
主机记录: wx.xiangyuan
记录值: 82.156.120.191
TTL: 10分钟 (600)
```

**Cloudflare：**
```
Type: A
Name: wx.xiangyuan
IPv4 address: 82.156.120.191
TTL: Auto
Proxy status: DNS only (先关闭小黄云，等全部配置完成后再开启)
```

> **注意**：如果该域名已经有 `*.hengtaisftech.com` 的通配符 A 记录，理论上 `wx.xiangyuan.hengtaisftech.com` 会自动匹配，不需要额外添加。但从 certbot 报错来看，目前并没有这条记录。

### 2.3 保存并等待生效

保存后，DNS 记录需要一定时间才能在全球生效，这取决于：
- 域名服务商的推送速度
- TTL 设置值
- 各地 DNS 缓存

通常 **几分钟到 1 小时内** 生效，个别情况可能需要更久。

### 2.4 验证 DNS 是否生效

在**你的服务器上**执行以下命令验证：

```bash
# 方法 1：dig
dig wx.xiangyuan.hengtaisftech.com +short

# 方法 2：nslookup
nslookup wx.xiangyuan.hengtaisftech.com

# 方法 3：在线工具（从外部网络验证）
# 浏览器访问 https://www.whatsmydns.net/#A/wx.xiangyuan.hengtaisftech.com
```

**必须看到返回 `82.156.120.191` 才能继续下一步。**

```bash
# 正确的输出示例：
$ dig wx.xiangyuan.hengtaisftech.com +short
82.156.120.191
```

如果无结果或显示其他 IP，**不要继续执行后续步骤**，继续等待或检查填写是否正确。

### 2.5 DNS 配置常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| `dig` 无结果 | 记录未保存、TTL 缓存、服务商未推送 | 等待 10~30 分钟后再试 |
| 返回了错误的 IP | 填错了记录值，或存在其他冲突记录 | 检查记录值是否为 `82.156.120.191`，删除冲突记录 |
| Cloudflare 开启代理（小黄云） | certbot 验证可能失败 | 先关闭代理（设为 DNS only），证书申请成功后再开启 |
| 提示域名未注册 | 在错误的账号/平台操作 | 确认登录的是管理 `hengtaisftech.com` 的正确账号 |

---

## 第三步：创建并启用 HTTP（80 端口）配置

**注意：此时只配置 80 端口，不要动 443。**

### 3.1 创建 80 端口配置文件

```bash
sudo tee /etc/apache2/sites-available/wx-xiangyuan.conf << 'EOF'
<VirtualHost *:80>
    ServerName wx.xiangyuan.hengtaisftech.com
    ServerAdmin webmaster@localhost
    DocumentRoot /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

    <Directory /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/wx-xiangyuan-error.log
    CustomLog ${APACHE_LOG_DIR}/wx-xiangyuan-access.log combined
</VirtualHost>
EOF
```

### 3.2 启用站点并重启 Apache

```bash
sudo a2ensite wx-xiangyuan.conf
sudo systemctl restart apache2
```

### 3.3 验证 80 端口是否正常

```bash
# 本地测试
curl -I http://wx.xiangyuan.hengtaisftech.com/
```

应返回 `200 OK`。

---

## 第四步：申请 Let's Encrypt SSL 证书

> **注意**：执行本步骤前，必须确保**第三步（80 端口配置）已完成且 Apache 正常运行**。certbot 需要通过 80 端口进行域名验证。

### 4.1 确认前置条件

- DNS 已生效（`dig` 能解析到 IP）
- 80 端口配置已启用且 Apache 正常运行
- 服务器 80 端口已对外开放

### 4.2 申请证书

```bash
sudo certbot certonly --webroot \
  -w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer \
  -d wx.xiangyuan.hengtaisftech.com
```

### 4.3 申请失败常见原因

| 错误信息 | 原因 | 解决 |
|----------|------|------|
| `NXDOMAIN` | DNS 未生效 | 等待 DNS 生效后再试 |
| `Connection refused` | 80 端口未开放 | 检查防火墙/安全组 |
| `Unauthorized` | Apache 未正确响应验证请求 | 确认 80 端口配置已启用 |

### 4.4 验证证书是否生成

```bash
ls -la /etc/letsencrypt/live/wx.xiangyuan.hengtaisftech.com/
```

应看到 `fullchain.pem` 和 `privkey.pem` 两个文件。

### 4.5 测试自动续期

```bash
sudo certbot renew --dry-run
```

---

## 第五步：创建并启用 HTTPS（443 端口）配置

**注意：必须在证书申请成功后，才能执行这一步。**

### 5.1 创建 443 端口配置文件

```bash
sudo tee /etc/apache2/sites-available/wx-xiangyuan-ssl.conf << 'EOF'
<VirtualHost *:443>
    ServerName wx.xiangyuan.hengtaisftech.com
    ServerAdmin webmaster@localhost

    DocumentRoot /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

    ErrorLog ${APACHE_LOG_DIR}/wx-xiangyuan-error.log
    CustomLog ${APACHE_LOG_DIR}/wx-xiangyuan-access.log combined

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/wx.xiangyuan.hengtaisftech.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/wx.xiangyuan.hengtaisftech.com/privkey.pem

    <FilesMatch "\.(?:cgi|shtml|phtml|php)$">
        SSLOptions +StdEnvVars
    </FilesMatch>
    <Directory /usr/lib/cgi-bin>
        SSLOptions +StdEnvVars
    </Directory>

    <Directory /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
EOF
```

### 5.2 启用 HTTPS 站点

```bash
sudo a2ensite wx-xiangyuan-ssl.conf
```

### 5.3 修改 80 端口配置为自动跳转 HTTPS

编辑 `/etc/apache2/sites-available/wx-xiangyuan.conf`，在 `ServerAdmin` 下方添加重定向规则：

```apache
    # 强制 HTTP 跳转到 HTTPS
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
```

修改后的完整内容：

```bash
sudo tee /etc/apache2/sites-available/wx-xiangyuan.conf << 'EOF'
<VirtualHost *:80>
    ServerName wx.xiangyuan.hengtaisftech.com
    ServerAdmin webmaster@localhost

    # 强制 HTTP 跳转到 HTTPS
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

    ErrorLog ${APACHE_LOG_DIR}/wx-xiangyuan-error.log
    CustomLog ${APACHE_LOG_DIR}/wx-xiangyuan-access.log combined
</VirtualHost>
EOF
```

### 5.4 确保必要模块已启用

```bash
sudo a2enmod ssl
sudo a2enmod rewrite
```

### 5.5 检查配置语法并重启 Apache

```bash
sudo apache2ctl configtest
```

如果显示 `Syntax OK`，则重启：

```bash
sudo systemctl restart apache2
```

**如果显示错误，先解决错误再重启，不要强行重启。**

---

## 第六步：验证

### 6.1 测试 HTTPS 访问

浏览器访问：

```
https://wx.xiangyuan.hengtaisftech.com/
```

应正常显示项目内容，地址栏有**小锁图标**。

### 6.2 测试 HTTP 自动跳转

```bash
curl -I http://wx.xiangyuan.hengtaisftech.com/
```

应返回 `301 Moved Permanently`，且 `Location` 头指向 `https://...`。

### 6.3 检查 Apache 状态

```bash
sudo systemctl status apache2
```

应显示 `active (running)`。

---

## 第七步：相关文件路径汇总

| 用途 | 路径 |
|------|------|
| 项目根目录 | `/home/ubuntu/project/xiangyuan/xiangyuan_clouldServer` |
| HTTP 配置（80） | `/etc/apache2/sites-available/wx-xiangyuan.conf` |
| HTTPS 配置（443） | `/etc/apache2/sites-available/wx-xiangyuan-ssl.conf` |
| SSL 证书目录 | `/etc/letsencrypt/live/wx.xiangyuan.hengtaisftech.com/` |
| Apache 错误日志 | `/var/log/apache2/wx-xiangyuan-error.log` |
| Apache 访问日志 | `/var/log/apache2/wx-xiangyuan-access.log` |

---

## 附录：常见问题排查

### Q1：Apache 重启失败，提示证书文件不存在

**原因**：先启用了 HTTPS 配置，但证书还没申请。  
**解决**：

```bash
# 临时禁用 HTTPS 配置
sudo a2dissite wx-xiangyuan-ssl.conf
sudo systemctl restart apache2

# 然后按正确顺序：先申请证书 → 再启用 HTTPS
```

### Q2：Certbot 报错 `NXDOMAIN`

**原因**：域名 DNS 未配置或未生效。  
**解决**：去域名管理后台添加 A 记录，等 `dig` 能解析到 IP 后再申请。

### Q3：PHP 无法写入文件（上传失败、日志写不了）

**原因**：`www-data` 没有写权限。  
**解决**：

```bash
# 给需要写入的目录添加组写权限
sudo chmod -R g+w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer/目标目录

# 或者改为 www-data 所有
sudo chown -R www-data:www-data /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer/目标目录
```

### Q4：Apache 能启动，但访问返回 403 Forbidden

**原因**：路径上某层目录缺少 `x`（进入）权限。  
**解决**：

```bash
# 检查完整路径权限
namei -l /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

# 给缺少 x 权限的目录补上
sudo chmod o+x /缺失的目录
```

---

## 附录：配置速查表

```bash
# ========== 1. 目录权限 ==========
sudo chmod o+rx /home/ubuntu /home/ubuntu/project /home/ubuntu/project/xiangyuan
sudo chown -R ubuntu:www-data /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer
sudo chmod -R u+rwX,go+rX,go-w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer

# ========== 2. 验证 DNS ==========
dig wx.xiangyuan.hengtaisftech.com +short

# ========== 3. 创建并启用 HTTP(80) ==========
# （见上文第三步，创建 wx-xiangyuan.conf）
sudo a2ensite wx-xiangyuan.conf
sudo systemctl restart apache2

# ========== 4. 申请证书 ==========
sudo certbot certonly --webroot -w /home/ubuntu/project/xiangyuan/xiangyuan_clouldServer -d wx.xiangyuan.hengtaisftech.com

# ========== 5. 创建并启用 HTTPS(443) ==========
# （见上文第五步，创建 wx-xiangyuan-ssl.conf）
sudo a2ensite wx-xiangyuan-ssl.conf
sudo a2enmod ssl rewrite
sudo apache2ctl configtest
sudo systemctl restart apache2

# ========== 6. 验证 ==========
curl -I http://wx.xiangyuan.hengtaisftech.com/   # 应返回 301
curl -I https://wx.xiangyuan.hengtaisftech.com/  # 应返回 200
```

---

*文档版本：v2（实战修正版）*  
*更新时间：2026-06-18*  
*核心教训：证书未申请前，绝不要启用 HTTPS 配置*