---
document_type: "installation_guide"
service: "POSTGRESQL"
title: "PostgreSQL 安裝指南 (本地部署)"
date: "2026-03-15"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "Warren"
tags:
  - "postgresql"
  - "database"
  - "macos"
  - "sql"
ai_query_hints:
  - "如何安裝 PostgreSQL 資料庫？"
  - "PostgreSQL 數據目錄路徑在哪裡？"
  - "如何卸載 PostgreSQL 並保留數據？"
---

# PostgreSQL 安裝指南 (本地部署)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |

---

## 概述

本文檔說明如何在 macOS 上安裝 PostgreSQL，配置為本地部署，支援遠端訪問。

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| PostgreSQL | ✅ 已安裝 v18.1 |
| 數據目錄 | /Users/accusys/momentry/var/postgresql |
| 日誌目錄 | /Users/accusys/momentry/log/ |
| Plist | /Library/LaunchDaemons/com.momentry.postgresql.plist |
| Launchd 狀態 | ✅ 已註冊 |
| RunAtLoad | ✅ 已設定 |
| KeepAlive | ✅ 已設定 |

### 重要更新 (2026-03-24)

1. **資料目錄已變更**: 從 `/opt/homebrew/var/postgresql@18` 遷移到 `/Users/accusys/momentry/var/postgresql`
2. **統一管理**: 所有 Momentry 服務現在都使用 `/Library/LaunchDaemons/` 下的自定義 plist
3. **避免衝突**: 刪除了 homebrew plist，避免 reboot 後使用舊資料目錄

---

## 安裝步驟

### Step 1: 安裝 PostgreSQL (使用 brew)

```bash
# 安裝 PostgreSQL
brew install postgresql@18
```

**驗證**:
```bash
postgres --version
# postgres (PostgreSQL) 18.1
```

---

### Step 2: 建立目錄結構

```bash
# 建立數據目錄
mkdir -p /Users/accusys/momentry/var/postgresql

# 建立配置目錄
mkdir -p /Users/accusys/momentry/etc/postgresql

# 建立日誌目錄
mkdir -p /Users/accusys/momentry/log

# 建立日誌文件
touch /Users/accusys/momentry/log/postgresql.log
touch /Users/accusys/momentry/log/postgresql.error.log

# 設定權限
chown -R accusys:staff /Users/accusys/momentry/var/postgresql
chown -R accusys:staff /Users/accusys/momentry/etc/postgresql
chown -R accusys:staff /Users/accusys/momentry/log
```

**注意**: 如果需要從舊數據遷移，需要先初始化新目錄:
```bash
# 初始化新數據目錄 (會創建默認數據庫)
initdb -D /Users/accusys/momentry/var/postgresql -U accusys
```

---

### Step 3: 使用 plist 開機自動啟動

```bash
# 複製 plist 到 LaunchDaemons 目錄
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.postgresql.plist /Library/LaunchDaemons/

# 載入並啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
```

---

## 監控配置

### 添加到監控配置

在 `monitor/config/monitor_config.yaml` 中添加：

```yaml
database:
  postgresql:
    enabled: true
    host: "localhost"
    port: 5432
    user: "accusys"
    database: "momentry"
```

### 添加健康檢查函數

在 `monitor/database/postgres_monitor.sh` 中已包含 PostgreSQL 監控。

---

## 卸載步驟

### 重要: 路徑說明

| 路徑 | 類型 | 說明 |
|------|------|------|
| `/Users/accusys/momentry/var/postgresql/` | 數據 | **不要刪除** - 數據目錄 |
| `/Users/accusys/momentry/etc/postgresql/` | 配置 | **不要刪除** - 配置目錄 |
| `/Users/accusys/momentry/log/` | 日誌 | **不要刪除** - 日誌目錄 |
| `/opt/homebrew/opt/postgresql@18/` | 安裝 | **刪除** - PostgreSQL 安裝目錄 |

### Step 1: 停止 PostgreSQL

```bash
# 找到 PostgreSQL 進程
ps aux | grep postgres | grep -v grep

# 停止 PostgreSQL
pg_ctl -D /opt/homebrew/var/postgresql@18 stop
# 或
pkill -f postgresql

# 確認停止
ps aux | grep postgres | grep -v grep || echo "PostgreSQL 已停止"
```

---

### Step 2: 卸載 PostgreSQL

```bash
# 卸載 PostgreSQL
brew uninstall postgresql@18

# 移除 plist
sudo launchctl unload /Library/LaunchDaemons/com.momentry.postgresql.plist
sudo rm /Library/LaunchDaemons/com.momentry.postgresql.plist
```

---

### Step 3: 刪除專屬檔案

```bash
# 刪除數據目錄 (可選)
rm -rf /Users/accusys/momentry/var/postgresql

# 刪除日誌 (可選)
rm -f /Users/accusys/momentry/log/postgresql.log
rm -f /Users/accusys/momentry/log/postgresql.error.log
```

**注意: 不要刪除以下共用目錄**:
```bash
# 這些是共用的，不要刪除!
# /Users/accusys/momentry/var
# /Users/accusys/momentry/log
```

---

### Step 4: 卸載後檢查清單

```bash
echo "=== PostgreSQL 卸載後檢查 ==="

# 1. 檢查 PostgreSQL 進程
echo "1. PostgreSQL 進程:"
ps aux | grep postgres | grep -v grep && echo "   ✗ 仍在運行" || echo "   ✓ 已停止"

# 2. Port 5432
echo "2. Port 5432:"
lsof -i :5432 > /dev/null 2>&1 && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"

# 3. postgres 命令
echo "3. postgres 命令:"
which postgres > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 4. brew 安裝
echo "4. brew 安裝:"
brew list postgresql@18 > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 5. launchctl 服務
echo "5. launchctl 服務:"
sudo launchctl list | grep postgresql > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 6. 數據目錄 (可選刪除)
echo "6. 數據目錄:"
[ -d "/Users/accusys/momentry/var/postgresql" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

# 7. 日誌目錄 (可選刪除)
echo "7. 日誌目錄:"
[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"
```

**預期結果**:
```
=== PostgreSQL 卸載後檢查 ===
1. PostgreSQL 進程:
   ✓ 已停止
2. Port 5432:
   ✓ 已釋放
3. postgres 命令:
   ✓ 已移除
4. brew 安裝:
   ✓ 已移除
5. launchctl 服務:
   ✓ 已移除
6. 數據目錄:
   ✓ 保留 (或 ✗ 已刪除)
7. 日誌目錄:
   ✓ 保留 (或 ✗ 已刪除)
```

---

## 手動檢查命令

```bash
# 1. 檢查進程
ps aux | grep postgres | grep -v grep

# 2. 檢查 Port
lsof -i :5432

# 3. 測試連線
psql -U accusys -l

# 4. 查看所有數據庫
psql -U accusys -c "\l"

# 5. 查看連接
psql -U accusys -c "\conninfo"

# 6. 查看表
psql -U accusys -d momentry -c "\dt"

# 7. 查看日誌
tail -20 /Users/accusys/momentry/log/postgresql.log
```

---

## 連線資訊

| 項目 | 值 |
|------|-----|
| Host | localhost |
| Port | 5432 |
| User | accusys |
| Database | momentry, video_register, gitea, n8n |

---

## 環境變數

在 `.env` 中:

```env
POSTGRES_URL=postgresql://accusys@localhost:5432
POSTGRES_DB=momentry
```

---

## 遠端訪問

- PostgreSQL 綁定到所有網路介面 (0.0.0.0)
- 本地網路其他機器可透過 IP 訪問
- 請設定 `pg_hba.conf` 限制訪問 IP

---

## 故障排除

### PostgreSQL 無法啟動

```bash
# 檢查日誌
tail -f /Users/accusys/momentry/log/postgresql.log

# 檢查目錄權限
ls -la /Users/accusys/momentry/var/postgresql/

# 重新設定權限
chown -R $(whoami):staff /Users/accusys/momentry/var/postgresql
```

### Port 被佔用

```bash
# 檢查哪個程序佔用 port 5432
lsof -i :5432

# 終止佔用程序
kill <PID>
```

### 需要重新載入 plist

```bash
# 卸載舊服務 (如果存在)
sudo launchctl unload /Library/LaunchDaemons/com.momentry.postgresql.plist 2>/dev/null

# 載入新服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
```

---

## 檔案位置

| 類型 | 路徑 | 說明 |
|------|------|------|
| 安裝 | `/opt/homebrew/opt/postgresql@18/` | PostgreSQL 安裝目錄 |
| 執行檔 | `/opt/homebrew/opt/postgresql@18/bin/postgres` | PostgreSQL 執行檔 |
| 數據目錄 | `/Users/accusys/momentry/var/postgresql/` | 數據儲存 |
| 日誌 | `/Users/accusys/momentry/log/postgresql.log` | 執行日誌 |
| 錯誤日誌 | `/Users/accusys/momentry/log/postgresql.error.log` | 錯誤日誌 |
| plist | `/Library/LaunchDaemons/com.momentry.postgresql.plist` | 開機啟動 |
| 備份 | `/Users/accusys/momentry/var/momentry_db_backup_latest.sql` | momentry 數據庫備份 |
| 備份 | `/Users/accusys/momentry/var/video_register_db_backup_latest.sql` | video_register 數據庫備份 |

---

## 備份與恢復

### 備份 (pg_dump)

```bash
# 備份 momentry 數據庫
pg_dump -U accusys momentry > /Users/accusys/momentry/var/momentry_db_backup_latest.sql

# 備份 video_register 數據庫
pg_dump -U accusys video_register > /Users/accusys/momentry/var/video_register_db_backup_latest.sql
```

### 恢復 (psql)

```bash
# 恢復 momentry 數據庫
psql -U accusys -d momentry < /Users/accusys/momentry/var/momentry_db_backup_latest.sql

# 恢復 video_register 數據庫
psql -U accusys -d video_register < /Users/accusys/momentry/var/video_register_db_backup_latest.sql
```

### 數據目錄複製 (完整遷移)

```bash
# 1. 停止 PostgreSQL
pg_ctl -D /Users/accusys/momentry/var/postgresql stop

# 2. 複製數據目錄
cp -r /opt/homebrew/var/postgresql@18/* /Users/accusys/momentry/var/postgresql/

# 3. 設定權限
chown -R $(whoami):staff /Users/accusys/momentry/var/postgresql

# 4. 啟動 PostgreSQL
sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
```

---

## 版本資訊

- 版本: 18.1
- Port: 5432
- User: accusys
- 數據目錄: /Users/accusys/momentry/var/postgresql/
- 日誌目錄: /Users/accusys/momentry/log/
