CORETH — Current System Architecture & Installation

1. Overview#

CORETH Context Processor คือระบบที่ติดตั้งในฝั่งลูกค้า (customer-local) ทำหน้าที่รับไฟล์จากต้นทาง แปลงเป็น Structured Data ที่มี schema ชัดเจน แล้ว project ต่อเป็น Structured Context (Entity / Fact / Relationship / Evidence) สำหรับให้ agent และแอปพลิเคชันปลายทางเรียกใช้

Django applications

การแยกนี้บังคับด้วย config/database_router.py → DomainRouter ซึ่ง route ทุก model ของ coreth_data ไป alias data เมื่อมี DATA_DATABASE_URL และ route ที่เหลือ (รวม django.contrib.auth) ไป default

สถานะของฟีเจอร์ในเอกสารนี้

2. Architecture#

ทุกกล่องและทุกลูกศรในหัวข้อนี้ตรวจกลับได้กับไฟล์จริงใน repository ถ้า component ไม่ปรากฏในโค้ด จะไม่อยู่ในไดอะแกรม

2.1 System Context#

ขอบเขตของระบบ: อะไรอยู่ใน Compose stack ของลูกค้า และอะไรเป็นบริการภายนอกที่ต้องพึ่งพา

2.2 Runtime / Deployment Topology#

ทุก service มาจาก compose.yaml (และ compose.cloudflare.yaml สำหรับ overlay) service ที่ไม่มี profile จะขึ้นเสมอเมื่อสั่ง docker compose up

Secret injection ตอน container เริ่มทำงาน

Dockerfile ตั้ง ENTRYPOINT ["python","-m","coreth_context.runtime_secrets"] ทุกคำสั่งจึงถูกห่อด้วย launcher ที่ resolve OPENAI_API_KEY_REF (ต้องขึ้นต้น aws-secretsmanager://) เข้าสู่ os.environ["OPENAI_API_KEY"] แล้วค่อย execvp คำสั่งจริง ถ้า resolve ไม่สำเร็จ process จบด้วย exit code 78 และไม่พิมพ์ค่า/reference ออก log

2.3 Main Data Flow#

เส้นทางจริงจากไฟล์ต้นทางจนถึง canonical Context ทุกขั้นขับเคลื่อนโดย runworker ซึ่งเรียก WorkerCycle.run_once() วนทุก WORKER_POLL_SECONDS (default 2 วินาที)

สิ่งที่ worker ทำในหนึ่งรอบ

2.4 Submission / Review Flow#

เส้นทางนี้ใช้ทั้งไฟล์ที่มาจาก File Ingestion และไฟล์ที่ผู้ใช้อัปโหลดตรงจาก OpenWebUI ต่างกันที่ว่า OpenWebUI สร้าง Submission ผ่าน API โดยตรง ขณะที่ FILE_READY สร้างจาก SourceSignal ในรอบของ worker

API ของ workflow นี้

นโยบายอนุมัติที่ทำงานจริง

ความขัดแย้งของข้อมูล (DataConflict)

เมื่อสองแหล่งเสนอค่าต่างกันในฟิลด์เดียวกันของ record เดียวกัน ระบบสร้าง DataConflict (unique ที่ dataset + record_key + field) สถานะ OPEN แถวนั้นจะไม่ถูกเผยแพร่จนกว่าคนจะตัดสินที่ /admin/data-conflicts หรือเรียก POST /api/v1/data-conflicts/{id}/resolve ลำดับความน่าเชื่อถือกำหนดด้วย SourceAuthorityPolicy (สร้างด้วย manage.py configure_source_authority)

2.5 Schema Improvement Flow#

SchemaImprovement คือข้อเสนอเปลี่ยนสัญญาโครงสร้างข้อมูลหนึ่งชุด มี unique constraint ที่ customer + environment + concept_key จึงมีข้อเสนอที่เปิดอยู่ได้เพียงหนึ่งต่อหนึ่งแนวคิด

อนุมัติอัตโนมัติได้แค่ไหน

schema_evolution.enabled() จะยอมให้อนุมัติอัตโนมัติก็ต่อเมื่อครบทุกข้อพร้อมกัน:

• CORETH_AUTO_APPROVE_ADDITIVE_SCHEMA=true (ค่าเริ่มต้น true)
• CORETH_REVIEW_PAUSE_APPLY=false
• source มี structured_data.auto_approve_additive ไม่ถูกตั้งเป็น false
• semantic_processing.mode เป็น AI_REQUIRED หรือ AI_OPTIONAL
• semantic_processing.allow_external_model = true
• EffectivePolicy มี ai.enabled = true

Schema Design (ออกแบบ schema ล่วงหน้าด้วย AI)

นอกจากข้อเสนอที่เกิดจากไฟล์จริง ยังมีเส้นทางออกแบบล่วงหน้า: POST /api/v1/schema-design รับไฟล์ตัวอย่าง/คำอธิบายแล้วสร้าง SchemaDesignPlan + SchemaDesignSource ให้ตรวจที่ /admin/schema-improvements เมื่อ source มี design ที่อนุมัติแล้ว (approved_designs()) การประมวลผลไฟล์จะยึด design นั้นแทนการเลือก field แบบเดิม IMPLEMENTED

2.6 Storage / Source-of-Truth Map#

แต่ละโดเมนมีเจ้าของเดียว อย่าเขียนข้ามโดเมนโดยตรง

2.7 Component Responsibilities#

Connector ที่มีในโค้ด

3. Prerequisites#

ตรวจให้ครบก่อนเริ่ม ทุกข้อในตารางนี้มาจากสิ่งที่โค้ดเรียกใช้จริง

3.1 ตรวจสิ่งที่ต้องมีด้วยสคริปต์เดียว

คัดลอกทั้งบล็อกไปวางใน shell บนเครื่องที่จะติดตั้ง ผลลัพธ์จะเป็น PASS / WARN / FAIL ต่อบรรทัด

# ตรวจเครื่องมือและสิทธิ์ที่ CORETH Context Processor ต้องใช้
AWS_REGION="${AWS_REGION:-ap-southeast-1}"
ok(){ printf 'PASS  %-26s %s\n' "$1" "$2"; }
wn(){ printf 'WARN  %-26s %s\n' "$1" "$2"; }
no(){ printf 'FAIL  %-26s %s\n' "$1" "$2"; }

command -v git   >/dev/null && ok git   "$(git --version)"            || no git   "ยังไม่ได้ติดตั้ง"
command -v docker >/dev/null && ok docker "$(docker --version)"         || no docker "ยังไม่ได้ติดตั้ง"
command -v python3 >/dev/null && ok python3 "$(python3 -V 2>&1)"      || no python3 "ยังไม่ได้ติดตั้ง (คู่มือนี้ใช้ในหลายขั้นตอน)"
docker compose version >/dev/null 2>&1 \
  && ok "docker compose" "$(docker compose version --short)" \
  || no "docker compose" "ต้องใช้ Compose plugin v2"
docker info >/dev/null 2>&1 && ok "docker daemon" "เข้าถึงได้" || no "docker daemon" "ผู้ใช้ปัจจุบันเรียก docker ไม่ได้"

if command -v aws >/dev/null; then
  ok "aws cli" "$(aws --version 2>&1 | cut -d' ' -f1)"
  ARN=$(aws sts get-caller-identity --query Arn --output text 2>/dev/null) \
    && ok "aws sts" "$ARN" || no "aws sts" "ไม่มี credential ที่ใช้ได้"
  aws secretsmanager list-secrets --max-results 1 --region "$AWS_REGION" >/dev/null 2>&1 \
    && ok "secretsmanager" "อ่านรายการ secret ได้ใน $AWS_REGION" \
    || no "secretsmanager" "ไม่มีสิทธิ์ list/GetSecretValue ใน $AWS_REGION"
else
  wn "aws cli" "ไม่มีบนเครื่องนี้ (container ใช้ IAM role ได้โดยไม่ต้องมี cli)"
fi

FREE=$(df -Pm . | awk 'NR==2{print $4}')
[ "$FREE" -ge 20480 ] && ok disk "เหลือ ${FREE} MB" || wn disk "เหลือ ${FREE} MB (แนะนำอย่างน้อย 20 GB)"

getent hosts api.openai.com >/dev/null 2>&1 && ok dns "api.openai.com แปลงชื่อได้" || wn dns "แปลงชื่อ api.openai.com ไม่ได้"

ผลลัพธ์ที่ควรเห็น

4. Install#

ทำตามลำดับ แต่ละขั้นมีคำสั่งเดียวและผลลัพธ์ที่ต้องเห็นก่อนไปขั้นถัดไป

sudo mkdir -p /opt/coreth && sudo chown "$USER":"$USER" /opt/coreth
git clone git@github.com:Core-technology-Co-Ltd/ai-coreth-context-processor.git /opt/coreth/app
cd /opt/coreth/app && git rev-parse --short HEAD

AWS_REGION="${AWS_REGION:-ap-southeast-1}"

# ---- ตัวช่วยเลือกจากรายการจริง ใช้ซ้ำได้ในขั้นตอนอื่น ----
select_one() {
  local title="$1" i=1 line n; local -a items=()
  while IFS= read -r line; do [ -n "$line" ] && items+=("$line"); done
  printf '\n%s\n' "$title"
  if [ "${#items[@]}" -eq 0 ]; then
    printf '  (ยังไม่มีข้อมูลในระบบ)\n'; read -r -p '  พิมพ์ค่าเอง: ' SELECTED </dev/tty; return
  fi
  for line in "${items[@]}"; do printf '  %d. %s\n' "$i" "$line"; i=$((i+1)); done
  if [ "${#items[@]}" -eq 1 ]; then
    SELECTED="${items[0]}"; printf '  เลือกอัตโนมัติ: %s\n' "$SELECTED"; return
  fi
  while :; do
    read -r -p "  เลือก [1-${#items[@]}]: " n </dev/tty
    case "$n" in ''|*[!0-9]*) ;; *)
      [ "$n" -ge 1 ] && [ "$n" -le "${#items[@]}" ] && { SELECTED="${items[$((n-1))]}"; return; };;
    esac
  done
}

# ---- 1) เลือก secret ที่มีอยู่ หรือสร้างใหม่ ----
NEW_LABEL='+ สร้าง secret ใหม่'
select_one "AWS Secrets Manager — เลือก secret ของ OpenAI" < <(
  aws secretsmanager list-secrets --region "$AWS_REGION" \
    --query 'SecretList[].Name' --output text 2>/dev/null | tr '\t' '\n' | sort
  printf '%s\n' "$NEW_LABEL"
)

# ---- 2) ถ้าเลือก "สร้างใหม่" ให้ถามชื่อและ key โดยไม่ echo ค่า ----
if [ "$SELECTED" = "$NEW_LABEL" ]; then
  read -r  -p '  ชื่อ secret ใหม่ (เช่น org/production/openai): ' SELECTED </dev/tty
  read -rs -p '  OpenAI API key (ไม่แสดงบนจอ): ' OPENAI_KEY </dev/tty; echo
  aws secretsmanager create-secret --region "$AWS_REGION" --name "$SELECTED" \
    --secret-string "$(OPENAI_KEY="$OPENAI_KEY" python3 -c \
        'import json,os;print(json.dumps({"OPENAI_API_KEY":os.environ["OPENAI_KEY"]}))')" >/dev/null
  unset OPENAI_KEY
fi

# ---- 3) ยืนยันว่า secret ที่เลือกมี key OPENAI_API_KEY จริง (ไม่พิมพ์ค่า) ----
if aws secretsmanager get-secret-value --region "$AWS_REGION" --secret-id "$SELECTED" \
     --query SecretString --output text 2>/dev/null \
   | python3 -c 'import json,sys
try: d=json.load(sys.stdin)
except Exception: sys.exit(1)
sys.exit(0 if isinstance(d,dict) and str(d.get("OPENAI_API_KEY","")).strip() else 1)'
then
  echo "PASS  $SELECTED มี key OPENAI_API_KEY"
else
  echo "FAIL  $SELECTED ไม่มี key OPENAI_API_KEY ที่ใช้ได้ — แก้ก่อนไปขั้นถัดไป"
  exit 1
fi

CORETH_AI_SECRET_REF="aws-secretsmanager://$SELECTED"
echo "CORETH_AI_SECRET_REF=$CORETH_AI_SECRET_REF"

python3 -c 'import uuid; print(uuid.uuid4())'

# list_source_policies --all-customers คืน JSON ของทุก source พร้อม customer_id
docker compose exec -T api python manage.py list_source_policies --all-customers \
  | python3 -c 'import json,sys
d=json.load(sys.stdin)
for c in sorted({s["customer_id"] for s in d["sources"]}): print(c)'

docker compose run --rm wizard

docker compose up --build -d && docker compose ps

docker compose logs migrate --tail=6

curl -sS http://127.0.0.1:"${CORETH_HTTP_PORT:-8080}"/health/live; echo

docker compose exec admin python manage.py bootstrap_root_user

docker compose run --rm ops python manage.py bootstrap_root_user

docker compose up -d worker && docker compose logs --tail=5 worker

ssh -N -L 8081:127.0.0.1:8081 ubuntu@YOUR_HOST

# 1) สร้าง tunnel + public hostname ใน Cloudflare Zero Trust dashboard
#    ตั้ง service ปลายทางเป็น http://cloudflare-origin:8080

# 2) เติมค่าลง .env (hostname เปล่า ๆ ห้ามมี https:// หรือ path)
printf 'COMPOSE_FILE=compose.yaml:compose.cloudflare.yaml\n' >> .env
printf 'CORETH_PUBLIC_HOST=context.example.com\n' >> .env
read -rs -p 'Cloudflare tunnel token: ' T; echo; printf 'CLOUDFLARE_TUNNEL_TOKEN=%s\n' "$T" >> .env; unset T
# เพิ่ม profile cloudflare เข้า COMPOSE_PROFILES ที่มีอยู่ (อย่าลบ local/admin เดิม)

# 3) ตรวจแล้ว deploy
docker compose config --quiet && docker compose up -d --build

docker compose logs --tail=20 cloudflared | grep -i "registered tunnel connection"

5. Configuration#

การตั้งค่าทั้งหมดผ่านตัวแปรสภาพแวดล้อมใน .env ที่ราก repository compose.yaml ประกาศ anchor &app-env แล้วทุก service ใช้ซ้ำด้วย *app-env ตัวแปรที่ไม่ปรากฏใน anchor นั้นจะไม่ถูกส่งเข้า container

5.1 บังคับต้องมี

5.2 ฐานข้อมูล

5.3 นโยบายการประมวลผลและอนุมัติ

5.4 ค่าที่เป็น secret reference (ห้ามใส่ค่าจริง)

5.5 ค่าที่ wizard สร้างหรือจัดการให้

5.6 ไม่มีผลเมื่อรันด้วย Docker Compose

ตัวแปรกลุ่มนี้อยู่ใน .env.advanced.example และถูกอ่านใน config/settings.py แต่ ไม่ได้อยู่ในบล็อก &app-env ของ compose.yaml จึงไปไม่ถึง container การแก้ใน .env จึงไม่มีผลใด ๆ

6. Source / Connector Setup#

Source configuration เป็น immutable — ทุกการแก้ไขสร้าง config_version ใหม่ และ latest_source_configurations() จะเลือกเฉพาะเวอร์ชันสูงสุดมาทำงาน ประวัติเดิมยังอยู่ครบเพื่อสืบย้อน lineage

6.1 File Ingestion (FILE_READY) IMPLEMENTED

ช่องทางหลักของไฟล์ที่เข้ามาอัตโนมัติ (Gmail, LINE, Web, API upload ฯลฯ) Context Processor ไม่ได้ต่อเข้ากล่องอีเมลเอง — มันคุยกับ File Ingestion service เท่านั้น

สิ่งที่ต้องเตรียมก่อน

• HTTPS base URL ของ File Ingestion — ต้องพิมพ์เอง (เป็นบริการภายนอก ระบบค้นหาให้ไม่ได้)
• Secret ของ service reader ใน Secrets Manager ที่มี key: issuer, audience, subject, kid, private_key และ (ไม่บังคับ) algorithm ค่าเริ่มต้น RS256
• สิทธิ์ file:read และ events:read ฝั่ง File Ingestion

ตั้งค่าผ่าน Admin (แนะนำ)

1. เปิด /admin/setup ด้วยบัญชีบทบาท ADMIN
2. เลือกประเภท File Ingestion แล้วกรอก base URL + secret reference
3. กดค้นหา — ระบบเรียก inventory จริงและ แสดงรายชื่อแหล่งข้อมูลที่พบให้เลือก (ingestion_source_options() แปลง source_type เป็นชื่อที่อ่านออก เช่น “Gmail — ฝ่ายขาย”) พร้อมเดา bucket ให้จาก inventory
4. เลือกโหมด schema: AI จัดการอัตโนมัติ หรือ กำหนด fields เอง
5. เลือกโมเดลจากปุ่มโหลดรายการ (/admin/setup/models) แล้วบันทึก

ตั้งค่าผ่าน CLI (สำหรับ automation)

docker compose exec api python manage.py configure_source \
  --source-type FILE_READY \
  --settings-file /app/examples/file-ingestion/thinkberry.json

พฤติกรรมเมื่อไม่ส่ง flag ครบ

ตรวจว่าเชื่อมต่อได้จริง

docker compose exec -T api python manage.py list_source_policies --issues-only

sources: [] = ไม่มี source ที่ policy ผิดพลาด ปิดกั้นไฟล์ดิบ หรือมี last_error_code ค้าง

นำไฟล์เดิมทั้งหมดเข้าครั้งแรก

onboard_file_ingestion ดึง inventory ทั้งหมด ตาม event ให้ทัน ประมวลผล และ project จนหมด — รันซ้ำได้ ไม่ทำงานซ้ำซ้อน เพราะมี FileIngestionCursor

docker compose exec api python manage.py onboard_file_ingestion

6.2 OpenWebUI direct upload (OPENWEBUI_UPLOAD) IMPLEMENTED

ผู้ใช้อัปโหลดไฟล์จาก OpenWebUI เข้ามาโดยตรงผ่าน POST /api/v1/submissions ด้วย Service JWT แล้วตรวจทานผลผ่าน /api/v1/openwebui/submissions ทุกไฟล์กลุ่มนี้ต้องมีคนกดยืนยันเสมอ ไม่มีเส้นทาง auto-approve

สร้าง source และผูกผู้ใช้ — เลือกจากรายการจริง

คำสั่งนี้ถามสามอย่าง: source ต้นแบบ, ศูนย์ และ OpenWebUI user id สองอย่างแรกมาเป็นเมนูตัวเลขจากฐานข้อมูล ส่วน user id ต้องพิมพ์เองเพราะเป็นตัวตนของระบบภายนอก

docker compose exec api python manage.py configure_openwebui_source

บทสนทนาจริง

นำ JSON ที่ได้ไปตั้งเป็น user map ฝั่ง OpenWebUI เพื่อให้ออก JWT ที่มี claim ตรงกัน

ออก Service grant

docker compose exec api python manage.py manage_tool_grant

Service JWT ที่ระบบยอมรับ

ทดสอบหนึ่งไฟล์แบบครบวงจร

1. อัปโหลดไฟล์จาก OpenWebUI (ระบบสร้าง Submission + OpenWebUIUploadReceipt)
2. รอ worker รัน ReviewJob(ANALYZE) — ดูสถานะที่ /admin/submissions
3. ตรวจแถวที่เสนอ แก้ค่าที่ผิด แล้วกดยืนยัน
4. ตรวจข้อมูลที่เผยแพร่แล้วที่ /admin/data-explorer

docker compose exec api python manage.py review_new_data

docker exec -it coreth-file-ingestion-api-1 \
  python manage.py configure_openwebui_archive \
  --subject service:context-processor

{
  "issuer": "https://context-processor.internal",
  "audience": "coreth-file-ingestion",
  "subject": "service:context-processor",
  "kid": "cp-archive-2026-01",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "algorithm": "RS256"
}

CORETH_OPENWEBUI_ARCHIVE_URL=https://files.example.com
CORETH_OPENWEBUI_ARCHIVE_SECRET_REF=aws-secretsmanager://org/production/file-ingestion-writer

docker exec coreth-context-processor-worker-1 python manage.py shell -c '
import os
from coreth_data.models import OpenWebUIUploadReceipt
from coreth_data.openwebui_archive import reconcile_openwebui_archives

customer = os.environ["CORETH_DEPLOYMENT_CUSTOMER_ID"]   # มาจาก .env ผ่าน compose
assert customer, "CORETH_DEPLOYMENT_CUSTOMER_ID ว่างในคอนเทนเนอร์"

pending = OpenWebUIUploadReceipt.all_objects.filter(
    customer_id=customer,
    submission__status="COMPLETED",
    revoked_at__isnull=True,
    archive_state__in=["PENDING", "RETRY"],
)
print("Queued:", pending.update(archive_next_attempt_at=None))
reconcile_openwebui_archives(limit=20)
'

# BLOCKED ไม่ถูกหยิบเองอีก ต้องรีเซ็ตกลับเป็น PENDING ก่อน
# sh -c + single quote: ตัวแปรถูกขยายในคอนเทนเนอร์ ไม่ใช่บน host
docker exec coreth-context-processor-worker-1 sh -c 'python manage.py reconcile_openwebui_archives \
  --retry-blocked --customer-id "$CORETH_DEPLOYMENT_CUSTOMER_ID"'

6.3 Connector อื่น ๆ ที่มีโค้ดแต่ไม่มีใน Admin UI

S3, GOOGLE_DRIVE, POSTGRESQL, MYSQL, MARIADB, REST มี adapter ครบใน coreth_context/connectors/ และตั้งค่าได้ด้วย manage.py configure_source --source-type … แต่หน้า /admin/setup เปิดให้เลือกแค่ FILE_READY กับ OPENWEBUI_UPLOAD

6.4 การหยุด / เปิดใหม่ / เก็บเข้าคลัง

7. Validation / Doctor / Health#

ระบบมีกลไกตรวจความพร้อมของตัวเองอยู่แล้ว ใช้มันแทนการเดา ContextDoctor ประเมินจากข้อเท็จจริงที่บันทึกไว้ในฐานข้อมูลเท่านั้น ผลลัพธ์จึงทำซ้ำได้ (deterministic)

7.1 ระดับความพร้อม

7.2 ลำดับเฟสของ readiness

7.3 รัน Doctor

ไม่ต้องใส่ --customer-id เพราะอ่านจาก CORETH_DEPLOYMENT_CUSTOMER_ID ให้เอง

docker compose exec -T api python manage.py context_doctor | python3 -m json.tool | head -40

ผลที่ต้องเห็น (ตัดมาบางส่วน)

สรุปเฉพาะข้อที่ไม่ผ่าน:

docker compose exec -T api python manage.py context_doctor | python3 -c '
import json,sys
r=json.load(sys.stdin)
for c in r["checks"]:
    print("{:5} {:26} {}".format(c["status"], c["code"], c["message"]))
print()
print("PHASE:", r["phase"], "| STATUS:", r["status"])
print("REASONS:", ", ".join(r["reason_codes"]) or "-")'

7.4 รายการตรวจทั้งหมดของ Doctor

ข้อที่ไม่ได้ทำให้เปลี่ยน phase โดยตรง ยังทำให้ phase เป็น BLOCKED (ถ้ามี FAIL) หรือ DEGRADED (ถ้ามี WARN) ได้ตามกฎรวมท้ายสุด

7.5 Smoke test ครบวงจรหนึ่งรอบ

ทดสอบเส้นทางจริงตั้งแต่ไฟล์เข้าจนถึงข้อมูลที่เผยแพร่ ใช้เวลาไม่กี่นาที

# 0) ค่าพื้นฐานจาก .env
set -a; . ./.env; set +a
PORT="${CORETH_HTTP_PORT:-8080}"

# 1) liveness ผ่าน Caddy
curl -fsS "http://127.0.0.1:$PORT/health/live" >/dev/null \
  && echo "PASS  api liveness" || echo "FAIL  api liveness"

# 2) migration ครบ (ไม่มีบรรทัดที่ยังไม่ติ๊ก)
docker compose exec -T api python manage.py migrate --check >/dev/null 2>&1 \
  && echo "PASS  migrations" || echo "FAIL  migrations (รัน docker compose run --rm migrate)"

# 3) worker เต้นอยู่จริง — บังคับหนึ่งรอบแล้วดูผลนับ
docker compose exec -T api python manage.py runworker --once

# 4) Doctor + readiness
docker compose exec -T api python manage.py context_doctor >/dev/null
curl -sS -o /tmp/ready.json -w 'HTTP %{http_code}\n' "http://127.0.0.1:$PORT/health/ready"
cat /tmp/ready.json; echo

# 5) dataset ที่เผยแพร่แล้ว
docker compose exec -T api python manage.py structured_data_status

# 6) งานตรวจทานที่ยังค้าง (อ่านอย่างเดียว ไม่เปลี่ยนสถานะ)
docker compose exec -T api python manage.py review_new_data

ผลที่ต้องเห็น

docker compose exec -T postgres psql -U coreth -d coreth_context -c \
  "SELECT count(*) FILTER (WHERE relrowsecurity) AS rls_on, count(*) AS total
   FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
   WHERE c.relkind='r' AND n.nspname='public';"

8. Operations#

งานประจำหลังติดตั้ง ทุกคำสั่งมีอยู่จริงใน repository

8.1 Deploy โค้ดใหม่โดยไม่ตัด ingestion

worker อยู่ใน profile แยกโดยเจตนา จึงอัปเดตเว็บได้โดยไม่แตะงานที่กำลังทำ แล้วค่อยรีสตาร์ต worker ตอนที่ว่าง

git pull
docker compose config --quiet                 # ตรวจไวยากรณ์ก่อนเสมอ
docker compose up -d --build --no-deps --wait --wait-timeout 300 api admin caddy

docker compose exec -T api python manage.py review_new_data   # ดูว่ามีอะไรค้างไหม
docker compose up -d --build --no-deps worker
docker compose logs --tail=10 worker

8.2 Upgrade ที่มี migration

scripts/upgrade.sh ห่อลำดับทั้งหมดไว้แล้ว: สำรอง → ซ้อมกู้คืน → Doctor → preflight → migrate → check → Doctor อีกครั้ง ทุกขั้นหยุดทันทีเมื่อผิดพลาด (set -eu)

docker compose exec api sh -c 'sh scripts/upgrade.sh "$CORETH_DEPLOYMENT_CUSTOMER_ID"'

สำหรับการย้อนกลับ (rollback) ต้องอ้างเอกสาร ADR ที่อนุมัติแล้ว:

docker compose exec api sh -c 'sh scripts/rollback-preflight.sh \
  "$CORETH_DEPLOYMENT_CUSTOMER_ID" "docs/adr/0003-multi-entity-schema-design.md"'

8.3 สำรองและกู้คืน

8.4 คำสั่งสำหรับงานประจำ

คำสั่งข้างต้นเรียกด้วยรูปแบบเดียวกัน: docker compose exec api python manage.py <command> (ใส่ -T เมื่อไม่ต้องการให้ถามโต้ตอบ เช่นในสคริปต์ CI)

8.5 ดู log

docker compose logs -f worker                       # JSON บรรทัดละ event
docker compose logs --tail=200 api | grep -i error
docker compose logs --tail=50 cloudflared           # เมื่อใช้ overlay

Log เป็น JSON เสมอ (coreth_context/logging.py::JsonLogFormatter) ฟิลด์ที่มีประโยชน์: event, customer_id, source_id, error_code, status · ระหว่างประมวลผลหนึ่ง signal จะเห็น signal_progress พร้อม phase (FETCH_METADATA → DOWNLOAD_CONTENT → FILE_AGENT_ANALYSIS หรือ EXTRACT_DOCUMENT) และเวลาที่ใช้

8.6 รันชุดทดสอบ

docker compose --profile test run --rm --build test

มีเทสต์ Python 64 ไฟล์ใน tests/ และเทสต์ UI ด้วย node --test (npm run test:explorer, npm run test:schema-design)

9. Troubleshooting#

อาการที่เกิดขึ้นได้จริงจากเส้นทาง error ที่มีในโค้ด เรียงตามสิ่งที่พบบ่อยตอนติดตั้ง

9.1 ติดตั้งและเริ่มระบบ

9.2 ความพร้อม (readiness)

9.3 การนำเข้าและประมวลผลไฟล์

9.4 การตรวจทานและ schema

9.5 ข้อมูลและฐานข้อมูล

10. Differences from Legacy Documentation#

เฉพาะข้อที่เปลี่ยนอย่างมีนัยสำคัญและพบระหว่างอ่านโค้ดจริงที่ commit 8d2a865 ไม่ใช่ changelog ทั้งหมด

เอกสารที่เหลืออยู่ใน docs/

เอกสารที่เนื้อหาถูกยกมารวมไว้ในฉบับนี้แล้วถูกลบทิ้ง (24 ไฟล์ · ยังกู้คืนได้จาก git history) ที่เหลือคือเอกสารที่ฉบับนี้ไม่ได้ครอบคลุม