OpenAPI: 관리 API 공개와 AI Agent

fn-knock의 Rust 관리 백엔드는 관리 엔드포인트 확인, 클라이언트 코드 생성 및 자동화 도구 연동에 사용할 수 있는 OpenAPI 3.0 문서를 제공합니다. 이 문서에서는 관리 백엔드가 127.0.0.1:7998에서 수신 대기하고 fn-knock 자체의 프로토콜 매핑을 사용하여 knock.example.com:7999에서 문서에 접근하는 구성을 예로 설명합니다.

관리 API는 매핑, 인증서, DDNS, WAF 및 기타 시스템 설정을 변경할 수 있습니다. 일반 공개 웹 페이지처럼 직접 노출하지 마십시오. 프로토콜 매핑 인증을 활성화하고 고정 출발지 IP, VPN 또는 다른 네트워크 접근 제한과 함께 사용합니다.

문서 엔드포인트

주소	내용
http://127.0.0.1:7998/docs	Swagger UI 대화형 문서
http://127.0.0.1:7998/docs/json	OpenAPI 3.0 JSON
http://knock.example.com:7999/docs	아래 매핑을 완료한 뒤 사용하는 외부 문서 엔드포인트

이 예시는 현재 인스턴스의 관리 백엔드 포트가 7998이라고 가정합니다. OpenWrt는 기본적으로 17998을 사용합니다. 포트를 사용자 지정했다면 실제 배포 설정을 사용합니다. 외부 매핑을 만들기 전에 fn-knock 호스트에서 로컬 /docs를 열어 백엔드 포트와 문서가 정상인지 확인합니다.

프로토콜 매핑으로 문서 공개

프로토콜 매핑은 도메인이 아니라 TCP/UDP와 포트를 기준으로 전달합니다. knock.example.com은 fn-knock의 공인 진입점 IP를 가리키기만 하면 됩니다. 이 경로를 실제로 구분하는 값은 외부 TCP 포트 7999입니다.

브라우저
  -> http://knock.example.com:7999/docs
  -> 라우터 또는 클라우드 방화벽에서 TCP 7999 허용
  -> fn-knock 프로토콜 매핑 TCP :7999
  -> 127.0.0.1:7998
  -> Swagger UI

1. 시스템 설정 → 모드를 열고 현재 모드가 서브도메인 모드인지 확인합니다.

2. 시스템 설정 → 기능에서 프로토콜 매핑을 활성화합니다.

3. 프로토콜 매핑에서 다음 규칙을 추가합니다.

   필드	예시
   전송 프로토콜	TCP
   외부 포트	7999
   메모	fn-knock OpenAPI
   대상 주소	127.0.0.1:7998
   인증 필요	활성화

4. 라우터에 “공인 TCP 7999 → fn-knock 호스트의 TCP 7999”를 설정합니다. 클라우드 서버는 보안 그룹에서도 같은 포트를 허용합니다. Docker 배포는 컨테이너 시작 설정에서 이 포트를 명시적으로 공개해야 합니다.

5. 인증 필요를 활성화했다면 같은 공인 인터넷 출구 IP에서 fn-knock 웹 로그인을 완료하고 로그인 후 IP 접근 허용이 꺼져 있지 않은지 확인합니다. 고정 출발지에는 IP/CIDR 접근 권한을 직접 추가할 수도 있습니다.

6. http://knock.example.com:7999/docs를 엽니다. 백엔드 7998은 기본적으로 HTTP를 제공합니다. 앞단에 TLS 종료를 별도로 설정하지 않았다면 예시를 바로 https://로 바꿀 수 없습니다.

Swagger UI는 jsDelivr에서 스크립트와 스타일을 불러옵니다. 브라우저가 이 CDN에 접근할 수 없으면 페이지가 비어 보일 수 있지만 /docs/json은 계속 직접 읽을 수 있습니다.

403 응답 또는 연결 실패

• 403 Forbidden: 일부 Docker, Linux, OpenWrt 및 Windows 배포는 보호된 관리 엔드포인트를 통해 요청이 들어오도록 요구합니다. 내부 백엔드에 직접 접근하면 거부됩니다. 이 보호를 유지하고 내부 프록시 헤더를 위조하거나 관리 패널을 우회하지 마십시오.
• 연결이 즉시 끊김: 프로토콜 매핑 인증, 현재 출발지 IP 접근 권한 및 자격 증명의 서비스 범위를 확인합니다.
• 연결 시간 초과: DNS, 라우터 포트 포워딩, 클라우드 보안 그룹, Docker 포트 공개 및 호스트 방화벽 순서로 확인합니다.
• 로컬에서는 열리지만 외부에서는 열리지 않음: 라우터가 내부 대상 포트 7998이 아니라 fn-knock의 외부 포트 7999로 전달하는지 확인합니다.

전체 플랫폼 제한과 문제 해결 방법은 TCP/UDP 스트림 프록시를 참고합니다.

OpenAPI 파일 가져오기

OpenAPI JSON을 로컬에 저장한 뒤 코드 생성기, API 클라이언트 또는 AI Agent에 전달할 수 있습니다.

curl --fail \
  http://knock.example.com:7999/docs/json \
  -o fn-knock-openapi.json

현재 문서는 주로 경로, HTTP 메서드 및 그룹 정보를 제공합니다. 일부 요청 본문, 응답 구조 및 인증 세부 정보에는 완전한 모델이 없을 수 있으므로 생성된 코드는 테스트 인스턴스에서 검증해야 합니다. 먼저 읽기 전용 GET 엔드포인트에서 응답 구조를 확인한 다음 쓰기 작업을 래핑합니다.

AI Agent에게 연동 코드 작성 요청

URL 또는 로컬 파일을 읽을 수 있는 AI Agent는 먼저 /docs/json을 확인하고 실제 작업에 맞는 Python, TypeScript, Go 또는 Shell 코드를 생성할 수 있습니다. 예:

http://knock.example.com:7999/docs/json을 읽고
TypeScript 클라이언트를 생성하세요.
1. 조회 엔드포인트만 구현하고 POST, PATCH, PUT 또는 DELETE를 호출하지 않습니다.
2. fn-knock 응답 래퍼와 2xx가 아닌 오류를 일관되게 처리합니다.
3. 기본 URL은 FN_KNOCK_API_BASE 환경 변수에서 읽습니다.
4. 모든 함수에 타입, 시간 제한 및 테스트를 생성합니다.
5. Cookie, 비밀번호 또는 Token을 소스 코드와 로그에 기록하지 않습니다.

설정을 변경할 때는 작업 범위, 대상 리소스 및 확인 절차를 프롬프트에 포함합니다. 예를 들어 Agent가 현재 상태를 읽고 변경 미리 보기를 출력한 뒤 사람의 확인을 받아야만 쓰기 엔드포인트를 호출하도록 요구합니다. OpenAPI가 요청 본문을 설명하지 않는다면 브라우저 개발자 도구에서 민감한 정보를 제거한 요청 예시도 함께 제공하여 실제 필드에 맞게 타입을 보완하도록 합니다.

생성된 코드를 사용하기 전에 최소한 다음 항목을 확인합니다.

1. 기본 주소가 의도한 인스턴스를 가리키는지 확인합니다.
2. 요청에 해당 배포에서 요구하는 관리 세션 또는 인증 정보가 포함되어 있는지 확인합니다.
3. 요청에 시간 제한이 있고 실패 응답을 처리하는지 확인합니다.
4. 쓰기 작업에 멱등성, 백업 또는 사람의 확인 절차가 있는지 확인합니다.
5. 로그에 Cookie, 자격 증명, 인증서 개인 키 및 내부 주소가 노출되지 않는지 확인합니다.

보안 범위

• VPN, 고정 공인 인터넷 출구 IP 또는 임시 포트 매핑을 통한 접근을 우선합니다. 전체 인터넷에 장기간 노출하지 않는 것이 좋습니다.

• 프로토콜 매핑의 인증 필요를 활성화합니다. 테스트가 끝나고 더 이상 필요하지 않으면 기능을 끄거나 규칙을 삭제합니다.

• /docs는 인터페이스 설명 페이지일 뿐 위험한 쓰기 작업을 안전하게 만들어 주지 않습니다. Swagger UI의 Try it out은 현재 인스턴스에 실제 요청을 보냅니다.

• /docs/json도 관리 엔드포인트 목록을 노출하므로 관리 영역의 일부로 취급합니다.

• 변경 전에 백업을 내보냅니다. 인증서, WAF, DDNS, 매핑 및 유지 관리 쓰기 엔드포인트는 비운영 환경에서 검증합니다.

• TCP/UDP 스트림 프록시

• 인증, 세션 및 서비스 범위

• IP 허용 목록

• 백업, 복원 및 데이터 정리