完善spec：Docker Compose部署方案及Django ORM管理数据模型

- 声明所有数据模型通过Django Model + Migration管理 - 新增Docker Compose部署章节（单服务web，远程NAS数据库） - 添加Dockerfile、compose.yml、.env模板、运维命令 - 预留Nginx反向代理配置 - hypertable通过RunSQL嵌入migration创建 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-05 13:18:58 +08:00
parent 82dd6e3f32
commit fc6d2c728f
1 changed files with 138 additions and 2 deletions
--- a/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md
+++ b/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md
@@ -71,6 +71,8 @@ session 文件位于 `agents/{agent_name}/sessions/` 路径下，从路径提取

 ## 4. 数据模型

+所有表结构通过 Django Model + Django Migration 进行定义和映射，不直接执行 DDL。TimescaleDB 的 hypertable 创建通过 `RunSQL` 操作嵌入 Django migration 中。
+
 ### 4.1 Session 表

 每个 JSONL 文件一条记录。
@@ -152,9 +154,10 @@ class ToolCall(models.Model):

 ### 4.4 TimescaleDB 时序优化

+- 在 Django 的最后一张数据表 migration 后，新增 migration 使用 `RunSQL` 创建 hypertables
 - `Session.start_time` 设为 hypertable 的分区列（按天分区）
 - `Message.timestamp` 设为 hypertable 的分区列（按天分区）
- `ToolCall.created_at` 设为 hypertable 的分区列（按天分区）
+- `ToolCall` 表使用关联 `Message.timestamp` 进行分区（不额外添加字段，通过消息时间推导）

 ## 5. 推送机制

@@ -263,7 +266,140 @@ Fields:
 | psycopg | 3.x |
 | 数据库分区 | 按天分区，保留 90 天热数据 |

-## 10. 非技术决策
+## 10. Docker Compose 部署
+
+### 10.1 架构决策
+
+- Docker Compose 仅管理 Django 应用服务（`web`），数据库连接远程 NAS 上的 PostgreSQL + TimescaleDB
+- Django 服务器与 NAS 处于同一局域网，通过内网 IP 直连
+- 所有可变配置通过 `.env` 文件注入，该文件加入 `.gitignore`
+
+### 10.2 项目结构
+
+```
+agent-base/
+├── docker-compose.yml      # 编排配置
+├── Dockerfile              # Django 镜像构建
+├── nginx/
+│   └── nginx.conf.placeholder  # Nginx 反代占位配置（预留）
+├── .env                    # 环境变量（不提交）
+├── .env.example            # 环境变量模板（提交）
+├── .dockerignore
+├── manage.py
+├── src/                    # Django 项目源码
+│   ├── openclaw/           # app
+│   └── config/             # 项目配置
+└── docs/                   # 文档
+```
+
+### 10.3 `.env` 配置
+
+```bash
+# .env.example（提交到仓库）
+# Django
+DJANGO_SECRET_KEY=CHANGE_ME
+DJANGO_PORT=8000
+DJANGO_ALLOWED_HOSTS=*
+
+# Database (NAS)
+DB_HOST=192.168.x.x
+DB_PORT=5432
+DB_NAME=openclaw_archive
+DB_USER=openclaw
+DB_PASSWORD=CHANGE_ME
+```
+
+`.env` 文件被加入 `.gitignore`，仅保留 `.env.example` 作为模板。
+
+### 10.4 Dockerfile
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE ${DJANGO_PORT:-8000}
+
+CMD ["gunicorn", "--bind", "0.0.0.0:${DJANGO_PORT:-8000}", \
+     "--workers", "4", "--timeout", "120", \
+     "config.wsgi:application"]
+```
+
+Gunicorn 4 个 worker，120 秒超时（解析 JSONL 可能耗时的场景）。
+
+### 10.5 docker-compose.yml
+
+```yaml
+services:
+  web:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: openclaw-archive
+    env_file:
+      - .env
+    ports:
+      - "${DJANGO_PORT:-8000}:${DJANGO_PORT:-8000}"
+    volumes:
+      - static_volume:/app/staticfiles
+      - jsonl_archive:/app/archive
+    restart: unless-stopped
+
+  # nginx 占位（预留）
+  # nginx:
+  #   image: nginx:alpine
+  #   container_name: openclaw-nginx
+  #   ports:
+  #     - "80:80"
+  #   volumes:
+  #     - ./nginx/nginx.conf:/etc/nginx/nginx.conf
+  #     - static_volume:/app/staticfiles:ro
+  #   depends_on:
+  #     - web
+
+volumes:
+  static_volume:
+  jsonl_archive:  # 原始 JSONL 归档存储
+```
+
+### 10.6 部署与运维命令
+
+```bash
+# 首次部署
+cp .env.example .env
+vim .env                     # 填写真实配置
+docker compose build
+docker compose run --rm web python manage.py migrate
+docker compose run --rm web python manage.py createsuperuser
+docker compose up -d
+
+# 日常运维
+docker compose ps              # 查看状态
+docker compose logs -f web     # 查看日志
+docker compose down            # 停止
+docker compose up -d --build   # 重建并重启
+
+# 数据库迁移
+docker compose run --rm web python manage.py makemigrations
+docker compose run --rm web python manage.py migrate
+```
+
+### 10.7 Nginx 反代（预留）
+
+当前阶段不使用 Nginx。`docker-compose.yml` 中已预留 Nginx 配置（注释状态），生产环境需要 HTTPS、静态文件优化时取消注释即可启用。
+
+启用前需将 `nginx/nginx.conf.placeholder` 重命名为 `nginx.conf` 并根据实际域名和证书路径修改配置。
+
+## 11. 非技术决策

 - 不接收 `.deleted.` 文件
 - 幂等上传：同一 session 重复推送时跳过（基于 session_id + agent_name 组合键）