# WordPress 安裝指南 (Portal)

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / big-pickle |

---

## 1. 概述

本文檔說明 Momentry Portal 的 WordPress 安裝配置，作為系統入口整合 n8n 自動化與 sftpgo 檔案服務。

---

## 2. 當前狀態

| 項目 | 狀態 |
|------|------|
| WordPress 版本 | 6.x |
| URL | https://wp.momentry.ddns.net |
| 安裝路徑 | `/Users/accusys/wordpress/web` |
| 資料庫 | wordpress (MariaDB) |
| 資料庫用戶 | wp_user |

---

## 3. 目錄結構

```
/Users/accusys/wordpress/
├── web/                          # WordPress 主目錄
│   ├── wp-admin/               # WordPress 管理面板
│   ├── wp-content/             # 內容目錄
│   │   ├── ai1wm-backups/     # 備份檔案 (*.wpress)
│   │   ├── languages/         # 語言檔案
│   │   ├── plugins/           # 插件目錄
│   │   ├── themes/            # 主題目錄
│   │   ├── uploads/           # 上傳檔案
│   │   └── cache/             # 快取目錄
│   ├── wp-includes/            # WordPress 核心
│   └── wp-config.php           # 配置文件
├── docker-compose.yml           # Docker 配置
└── wordpress_backup.sql         # 資料庫備份
```

### 空間使用

| 目錄 | 大小 | 說明 |
|------|------|------|
| `ai1wm-backups/` | ~250MB | 完整備份 (保留 2 個) |
| `plugins/` | 80MB | 插件 |
| `themes/` | 14MB | 主題 |
| `uploads/` | 12MB | 上傳檔案 |

---

## 4. 程式碼位置

自訂程式碼存放位置：

| 類型 | 路徑 |
|------|------|
| 主題 | `/Users/accusys/wordpress/web/wp-content/themes/` |
| 插件 | `/Users/accusys/wordpress/web/wp-content/plugins/` |
| 必須插件 | `/Users/accusys/wordpress/web/wp-content/mu-plugins/` |

---

## 5. 插件清單

| 插件 | 用途 | 說明 |
|------|------|------|
| elementor | 頁面建構 | 視覺化頁面編輯器 |
| all-in-one-wp-migration | 網站遷移/備份 | 完整網站備份工具 |
| akismet | 垃圾留言過濾 | 保護留言區域 |
| code-snippets | 自訂程式碼 | 無需修改主題即可添加 PHP |

### Elementor 版本
- 版本: 最新穩定版
- 用途: 頁面建構（開發階段）

### 未來計畫
- Phase 2: OpenCode 重構
- 目標: 交付無 Elementor 依賴版本

---

## 6. 主題清單

| 主題 | 說明 |
|------|------|
| twentytwentyfive | 目前使用主題 |
| twentytwentyfour | 備用 |
| twentytwentythree | 備用 |

---

## 7. 整合計畫

### 7.1 n8n 整合

n8n 作為自動化引擎，WordPress 頁面透過 REST API 或 Webhook 與 n8n 通訊。

| 整合方式 | 說明 |
|----------|------|
| REST API | WordPress 呼叫 n8n API |
| Webhook | n8n 觸發 WordPress 動作 |

### 7.2 sftpgo 整合

sftpgo 作為檔案服務，WordPress 頁面提供檔案上傳/下載功能。

| 整合方式 | 說明 |
|----------|------|
| WebDAV | 透過 WebDAV API 操作檔案 |
| REST API | 透過 sftpgo API 操作檔案 |

---

## 8. 管理命令

### 8.1 清理 ai1wm 備份

```bash
# 查看現有備份
ls -lt /Users/accusys/wordpress/web/wp-content/ai1wm-backups/*.wpress

# 保留最近 2 個，刪除舊的
ls -t /Users/accusys/wordpress/web/wp-content/ai1wm-backups/*.wpress | tail -n +3 | xargs rm

# 驗證結果
du -sh /Users/accusys/wordpress/web/wp-content/ai1wm-backups/
```

### 8.2 清理 WordPress 快取

```bash
# 刪除 Object Cache
wp cache flush

# 刪除 Elementor 快取
wp elementor flush_css

# 刪除全部快取
wp cache flush && wp elementor flush_css
```

### 8.3 資料庫操作

```bash
# 匯出資料庫
mysqldump -u wp_user -p wordpress > wordpress_backup.sql

# 匯入資料庫
mysql -u wp_user -p wordpress < wordpress_backup.sql
```

### 8.4 權限檢查

```bash
# 檢查目錄權限
ls -la /Users/accusys/wordpress/web/wp-content/

# 確認 wp-content 可寫入
chown -R _www:_www /Users/accusys/wordpress/web/wp-content/
chmod -R 755 /Users/accusys/wordpress/web/wp-content/
```

---

## 9. 故障排除

### 9.1 常見問題

| 問題 | 解決方案 |
|------|----------|
| 頁面載入緩慢 | 清理 Elementor/Object Cache |
| 上傳檔案失敗 | 檢查 wp-content/uploads 權限 |
| 502/504 錯誤 | 重啟 PHP-FPM |
| 資料庫連線失敗 | 檢查 wp-config.php 設定 |

### 9.2 診斷命令

```bash
# 檢查 PHP-FPM 狀態
lsof -i :9000

# 檢查 MySQL/MariaDB 狀態
lsof -i :3306

# 檢查 Apache/Nginx 狀態
lsof -i :80

# 查看 WordPress 錯誤日誌
tail -100 /Users/accusys/momentry/log/php-fpm.log
```

---

## 10. 開發協作

### 10.1 與 marcom 團隊協作

| 角色 | 負責 |
|------|------|
| marcom 團隊 | Figma 設計 / Elementor 建構 |
| OpenCode | 程式碼實作 / 重構 |

### 10.2 開發流程

```
Phase 1: marcom 建構 (現在)
└── Elementor 頁面建構

Phase 2: 交付審視 (TBD)
└── 功能確認 / 重構評估

Phase 3: OpenCode 重構 (討論後)
└── 純程式碼實作
└── 交付客戶 (無 Elementor 依賴)
```

---

## 11. PHP LSP 開發環境

### 11.1 軟體需求

| 軟體 | 版本 | 安裝方式 |
|------|------|----------|
| PHP | 8.0+ | 已安裝 (8.5.2) |
| Composer | 2.0+ | `brew install composer` |
| phpactor | Latest | PHAR 安裝 |

### 11.2 安裝步驟

#### 1. 安裝 Composer

```bash
brew install composer
```

#### 2. 安裝 phpactor

```bash
curl -sSL https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar -o ~/bin/phpactor
chmod +x ~/bin/phpactor
export PATH="$HOME/bin:$PATH"
```

#### 3. 安裝 WordPress Stubs

```bash
cd /Users/accusys/wordpress/web
composer require --dev php-stubs/wordpress-stubs
```

#### 4. 設定 phpactor

```bash
# 設定檔位置
mkdir -p ~/.config/phpactor

# 設定內容
cat > ~/.config/phpactor/phpactor.json << 'EOF'
{
    "core.min_memory_limit": 1610612736,
    "worse_reflection.additive_stubs": [
        "/Users/accusys/wordpress/web/vendor/php-stubs/wordpress-stubs/wordpress-stubs.php"
    ]
}
EOF
```

#### 5. 建立索引

```bash
cd /Users/accusys/wordpress/web
~/bin/phpactor index:build --reset
```

### 11.3 OpenCode 使用方式

```bash
# 確認安裝
~/bin/phpactor --version

# 查詢類別
~/bin/phpactor class:search "WP_User"

# 查看類別資訊
~/bin/phpactor index:query WP_User

# 導航到定義
~/bin/phpactor navigate /path/to/file.php

# 查詢參照
~/bin/phpactor references /path/to/file.php
```

### 11.4 常用指令

| 指令 | 用途 |
|------|------|
| `phpactor class:search` | 搜尋類別 |
| `phpactor index:query` | 查詢索引 |
| `phpactor index:build` | 建立索引 |
| `phpactor index:clean` | 清除索引 |
| `phpactor config:dump` | 顯示設定 |

---

## 12. 檔案位置

| 類型 | 路徑 | 說明 |
|------|------|------|
| WordPress 主目錄 | `/Users/accusys/wordpress/web` | 網站根目錄 |
| 備份目錄 | `/Users/accusys/momentry/backup/wordpress/` | 每日備份 |
| 日誌目錄 | `/Users/accusys/momentry/log/` | PHP/Apache 日誌 |
| phpactor | `~/bin/phpactor` | PHP LSP 主程式 |
| phpactor 設定 | `~/.config/phpactor/phpactor.json` | LSP 設定檔 |
| WordPress Stubs | `/Users/accusys/wordpress/web/vendor/php-stubs/` | WordPress 函數定義 |