ai-code-app/etc/servers/work-server

Work Server

Fastify + Knex + PostgreSQL 기반의 범용 작업용 API 서버입니다.

추천 DB

• PostgreSQL
• 이유:
  • Node 생태계에서 검증된 조합
  • Knex로 CRUD와 DDL을 함께 다루기 편함
  • 운영/확장/마이그레이션 측면에서 무난함

실행

docker compose up -d
docker compose logs -f work-server

work-server는 HMR/watch 없이 빌드 산출물(dist)을 실행합니다. 컨테이너 재기동은 docker compose up -d --build --force-recreate --no-deps work-server 기준으로 최신 소스를 다시 빌드한 뒤 새 컨테이너를 띄웁니다.

호스트 프로젝트 루트와 동일한 문맥으로 서버 재기동을 처리하려면 별도 host runner도 함께 켭니다.

cd /home/how2ice/project/ai-code-app
npm run server-command:runner

환경 변수

기본 실행은 .env.example 값으로도 가능합니다. 로컬 환경에 맞는 값을 덮어쓰려면 .env.example를 참고해서 .env를 추가하면 됩니다.

주요 항목:

• APP_TIME_ZONE: Node 서버 런타임 기준 시간대. 기본값 Asia/Seoul
• DB_TIME_ZONE: 앱이 여는 DB 세션 시간대. 기본값 Asia/Seoul
• DB_*: PostgreSQL 접속 정보
• PLAN_WORKER_ENABLED: Plan 자동화 worker 활성화 여부
• PLAN_WORKER_INTERVAL_MS: Plan polling 주기
• PLAN_GIT_REPO_PATH: 브랜치 생성/병합 대상 저장소 경로
• PLAN_MAIN_PROJECT_REPO_PATH: main 반영 후 pull 받을 메인 루트 프로젝트 경로. 비우면 PLAN_GIT_REPO_PATH를 사용
• PLAN_RELEASE_BRANCH: 자동 merge 대상 release 브랜치명
• IOS_NOTIFICATION_ENABLED: iOS APNs 알림 활성화 여부
• APNS_*: Apple Push Notification 인증 키 정보
• SERVER_COMMAND_DOCKER_SOCKET: 서버 재기동 명령이 사용할 Docker Unix socket 경로. rootless Docker면 예: /run/user/1000/docker.sock
• SERVER_COMMAND_API_BASE_URL: work-server가 서버 재기동 요청을 위임할 host runner 주소
• SERVER_COMMAND_API_ACCESS_TOKEN: host runner 호출 토큰

서버 재기동 기능을 쓰려면 work-server 컨테이너가 Docker에 접근할 수 있어야 합니다. 기본값은 /var/run/docker.sock이며, rootless Docker 환경이면 .env에 SERVER_COMMAND_DOCKER_SOCKET 또는 DOCKER_HOST=unix:///run/user/<uid>/docker.sock를 맞춰 준 뒤 work-server를 다시 올려야 합니다.

기본 예시는 http://host.docker.internal:3211/api로 맞춰져 있어서, work-server 컨테이너가 아니라 호스트의 현재 프로젝트 루트에서 restart-*.sh를 실행합니다. 즉 Server > Command가 직접 CLI로 재기동한 것과 최대한 비슷한 문맥을 사용합니다.

Codex Live

Codex Live는 현재 프로젝트 환경의 main_project 경로를 기준으로 실행됩니다. 기본값은 PLAN_MAIN_PROJECT_REPO_PATH=/workspace/main-project이며, 소스 수정이 필요하면 이 경로의 실제 프로젝트를 바로 수정합니다.

현재 운영 기준에서는 Codex Live, 일반 채팅, 작업메모 반영 요청 모두 현재 프로젝트 루트의 로컬 main 작업본을 바로 수정합니다. 별도 브랜치 생성이나 release -> main 동기화는 기본 전제로 사용하지 않으며, Git 관련 작업은 사용자가 명시적으로 요청할 때만 수행합니다.

브라우저 기준 접속 확인, 화면 검증, 외부 도메인 테스트는 https://test.sm-home.cloud/를 기본 작업 도메인으로 사용합니다. 별도 요청이 없는 한 sm-home.cloud나 rel.sm-home.cloud는 기본 검증 대상으로 삼지 않습니다.

채팅에서 파일, 문서, 이미지, 코드 같은 리소스를 제공할 때의 기본 공개 경로는 public/.codex_chat/<chat-session-id>/resource/...입니다. Codex가 원본 파일 경로만 답해도 서버가 이 위치로 세션 전용 사본을 만들고, 채팅에는 공개 URL을 다시 적어 줍니다.

채팅 첨부 파일도 같은 기준을 사용하며 public/.codex_chat/<chat-session-id>/resource/uploads/... 아래에 저장됩니다.

Plan 자동화

Plan 게시판 항목을 작업 큐처럼 읽어 자동화할 수 있습니다.

현재 로컬 운영 모드에서는 아래 자동 브랜치 흐름을 기본 동작으로 강제하지 않습니다. 필요 시 사용자가 별도로 요청한 경우에만 사용합니다.

• 등록 상태: worker가 읽어서 feature/plan-{id}-{workId} 브랜치 생성 시도
• 성공 시: 작업중, 브랜치준비
• 실패 시: 이슈, 최근 오류 기록
• 개발완료 상태: worker가 release 브랜치 병합 시도
• 병합 성공 시: 완료
• 병합 실패 시: 이슈

안전 조건:

• Git worktree가 깨끗해야 동작
• release 브랜치가 실제로 존재해야 병합 가능
• 실패 시 자동으로 이슈 상태와 오류 메시지를 남김

주요 API

• GET /health
• GET /api/schema/tables
• POST /api/ddl/create-table
• POST /api/ddl/drop-table
• POST /api/ddl/add-column
• POST /api/ddl/drop-column
• POST /api/ddl/raw
• POST /api/crud/:table/select
• POST /api/crud/:table/insert
• PATCH /api/crud/:table/update
• DELETE /api/crud/:table/delete
• GET /api/plan/statuses
• POST /api/plan/setup
• GET /api/plan/items
• GET /api/plan/items/:id
• POST /api/plan/items
• PATCH /api/plan/items/:id
• DELETE /api/plan/items/:id
• POST /api/notifications/setup
• GET /api/notifications/tokens
• PUT /api/notifications/tokens/ios
• DELETE /api/notifications/tokens/ios
• POST /api/notifications/send-test

iOS 알림 연동

• 프론트에서 알림 On 시 PUT /api/notifications/tokens/ios로 APNs 토큰을 등록합니다.
• 프론트에서 알림 Off 시 또는 토큰이 폐기되면 DELETE /api/notifications/tokens/ios로 토큰을 제거합니다.
• Plan worker가 브랜치 준비, 자동 작업 완료/실패, release 반영 완료/실패, main 반영 완료/실패 시 등록된 iOS 토큰으로 APNs 알림을 전송합니다.