🌐 docs.adcarry.ai 배포 시스템¶

2026-05-17 v1 박제. MkDocs Material + Cloudflare Pages 자동 배포 라인.

한눈에 보기¶

~/.openclaw/workspace/adcarry-docs/        ← 로컬 정본 (이 사이트)
        ↓ git push origin main
GitHub: chief-prog/adcarry-docs
        ↓ webhook 자동 트리거
Cloudflare Pages: adcarry-docs (source=github)
        ↓ pip install -r requirements.txt && mkdocs build
docs.adcarry.ai (Cloudflare Access 보호)

소요 시간: push → 라이브 약 1~2분.

1. 기술 스택¶

레이어	도구	버전
문서 작성	Markdown + frontmatter	—
정적 사이트 빌더	MkDocs Material	≥ 9.5.0
확장	pymdown-extensions, mkdocs-mermaid-zoom	—
빌드 환경	Cloudflare Pages (Python 3.13)	—
호스팅	Cloudflare Pages	Free plan
DNS	Cloudflare (proxied CNAME)	—
인증	Cloudflare Access + Google Workspace `@adcarry.co.kr`	—

2. 인프라 정본¶

자산	값
Cloudflare account	`Chief@adcarry.co.kr`
account_id	`dc35589e32a2d744c6a7dbf13eb0a212`
zone	`adcarry.ai`
zone_id	`31bbd3bbc33fd5abba3535ee4ad3143c`
Pages 프로젝트	`adcarry-docs`
source	`github` (chief-prog/adcarry-docs)
Production branch	`main`
Build command	`pip install -r requirements.txt && mkdocs build`
Output dir	`site`
Custom domain	`docs.adcarry.ai`
기본 URL	`adcarry-docs.pages.dev`

Cloudflare API Token¶

위치: ~/.openclaw/credentials/notes/cloudflare.env (0600)
이름: openclaw-adcarry-main
타입: User API Token (Account Token ❌)
만료: 2026-11-30
권한: Account (Pages/Workers/KV/R2/Tunnel/Access/Settings) + Zone (DNS/SSL/Zone Read)

3. 일상 배포 흐름¶

cd ~/.openclaw/workspace/adcarry-docs

# 1. 편집
$EDITOR docs/<섹션>/<페이지>.md

# 2. 로컬 미리보기 (선택)
mkdocs serve  # http://localhost:8000

# 3. push
git add docs/ mkdocs.yml requirements.txt
git commit -m "docs: <변경 요약>"
git push origin main

# 4. 1~2분 후 https://docs.adcarry.ai 갱신 확인

자동 트리거: GitHub webhook이 push를 받으면 Cloudflare Pages가 자동 빌드.

4. 빌드 상태 확인 (API)¶

source ~/.openclaw/credentials/notes/cloudflare.env
ACC=dc35589e32a2d744c6a7dbf13eb0a212
PROJ=adcarry-docs

curl -s "https://api.cloudflare.com/client/v4/accounts/$ACC/pages/projects/$PROJ/deployments?per_page=1" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  | python3 -c "import json,sys; d=json.load(sys.stdin)['result'][0]; [print(f\"  {s['name']:12} {s['status']}\") for s in d['stages']]"

출력 예:

  queued       success
  initialize   success
  clone_repo   success
  build        success
  deploy       success

5. 트러블슈팅 — 검증된 3건¶

❌ `path set in custom_dir does not exist`¶

원인: mkdocs.yml에 custom_dir: overrides가 박혔는데 디렉토리가 비어있어 git push 안 됨.

처치: 둘 중 하나 - 라인 제거 (디렉토리 안 쓸 경우) - overrides/.gitkeep 빈 파일 추가 (자리 보존)

❌ `plugin "X" is not installed`¶

원인: mkdocs.yml plugins에 박혔는데 requirements.txt 누락.

처치: requirements.txt에 추가 → commit → push. 이번 사례: mkdocs-mermaid-zoom.

룰: mkdocs.yml의 plugins: 변경 시 requirements.txt 동시 업데이트.

❌ `Could not detect a directory containing static files`¶

원인: Cloudflare 대시보드에서 Workers 프로젝트로 만들어짐 (Pages 아님).

처치: 프로젝트 삭제 후 직접 URL로 Pages 모드 생성:

https://dash.cloudflare.com/<account_id>/workers-and-pages/create/pages/connect-to-git

6. 핵심 함정 (학습)¶

⚠️ Direct Upload ↔ GitHub 모드 전환 불가¶

Cloudflare Pages 프로젝트는 생성 시점에 모드가 결정됨. 사후 변경 ❌. 재생성만이 유일 해법.

⚠️ 옛 프로젝트 삭제 시 도메인·DNS 동반 손실¶

Custom domain 매핑 삭제됨
CNAME 레코드 자동 제거됨
사고 시 다운타임: 약 15분 (도메인 재연결 + 인증서 발급)

⚠️ 도메인·DNS 복구 (API 2콜)¶

# 1. 새 프로젝트에 도메인 추가
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACC/pages/projects/$PROJ/domains" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "docs.adcarry.ai"}'

# 2. DNS CNAME 재생성
curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE/dns_records" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "CNAME", "name": "docs", "content": "adcarry-docs.pages.dev", "proxied": true}'

2분 후 status: active, validation: active.

7. 언어 정책¶

adcarry-docs/docs/ 산출물은 100% 한국어.

이유: docs.adcarry.ai는 사람용. 영문은 LLM 효율을 위한 partial만 적용 (workflow.md). 사람이 읽는 문서는 한국어로 박제.

정본(workspace*/AGENTS.md)에 영문 섹션이 있더라도 docs로 옮길 때는 한국어 번역.

8. 보안¶

Cloudflare Access 정책: Google Workspace @adcarry.co.kr 도메인만 통과
리다이렉트 호스트: adcarry-co.cloudflareaccess.com
외부 검수자: 별도 게스트 정책 또는 임시 token 발급 필요 (미구현)

9. 갱신 알림¶

자산	만료	대응
Cloudflare API Token	2026-11-30	만료 1주 전 수동 갱신
Cloudflare Access 정책	무기한	—
GitHub Fine-grained PAT	2026-08-13	macOS keychain 저장 (git remote는 HTTPS 깨끗), 만료 1주 전 재발급

10. 관련 문서¶

인프라 정본: wiki/concepts/docs-deployment.md
시크릿 인덱스: ~/.openclaw/credentials/notes/secrets-index.md
배포 스킬: workspace/skills/docs-deploy/SKILL.md
거버넌스 개요: governance/index.md

11. 변경 이력¶

날짜	변경
2026-05-17	v1 박제. Direct Upload → GitHub 모드 마이그레이션. mermaid-zoom 추가.
2026-05-17	Cloudflare API 자동화 라인 구축 (도메인·DNS API 복구 검증).