네트워크 공유

많은 산업 현장에서는 파일을 로컬 네트워크의 NAS나 Windows 파일 서버에 보관합니다 — 스캔 결과는 \\nas\production에 저장되고, 리포트는 공유 폴더에서 읽어오며, 기계들은 SMB를 통해 파일을 주고받습니다. IronFlock 앱은 이러한 공유를 컨테이너에 직접 마운트할 수 있으므로, 코드에서 로컬 디렉터리처럼 읽고 쓸 수 있습니다.

이는 파일 저장소의 온프레미스 대응물입니다: 파일 저장소가 플랫폼의 관리형 객체 저장소라면, 네트워크 공유는 고객의 LAN에 있는 고객 소유의 파일 서버입니다. 파일이 고객의 기존 인프라에 저장되어야 할 때 공유를 사용하십시오.

두 가지 프로토콜이 지원됩니다: SMB/CIFS(Windows 파일 서버 및 사실상 모든 NAS)와 NFS(Linux 기반 서버에서 일반적)입니다.

작동 방식

마운트는 Docker에 내장된 local 볼륨 드라이버를 사용하여 앱의 docker-compose.yml에 명명된 볼륨(named volume)으로 선언됩니다. 컨테이너가 시작될 때 디바이스의 Docker 엔진이 직접 마운트를 수행합니다 — 디바이스에 아무것도 설치할 필요가 없으며, 디바이스 사용자가 명령줄을 다룰 일도 전혀 없습니다.

공유의 주소와 자격 증명은 compose 파일에 직접 기록되지 않습니다. 이들은 ${VARIABLE} 플레이스홀더로, 앱 파라미터를 통해 디바이스별로 채워집니다 — 다른 모든 디바이스별 설정과 동일한 메커니즘입니다. 사용자는 각 디바이스에서 앱의 파라미터 양식으로 공유를 구성하고(또는 디바이스 그룹별로 한 번만 설정), 앱을 재시작합니다.

볼륨 선언

docker-compose.yml에 driver_opts를 가진 명명된 볼륨을 추가하고, 이를 필요로 하는 서비스에 마운트합니다:

services:
  app:
    build: .
    volumes:
      - netshare:/mnt/share
    restart: unless-stopped
 
volumes:
  netshare:
    # Docker 볼륨은 생성 당시의 설정을 계속 유지합니다. 리비전 파라미터를
    # 볼륨 이름에 포함해 두면, 리비전을 올리고 앱을 재시작하는 것만으로
    # 현재 설정을 가진 새 볼륨이 생성됩니다.
    name: "${APP_NAME}_share_r${SHARE_REV:-1}"
    driver: local
    driver_opts:
      type: cifs
      device: "//${SHARE_HOST}/${SHARE_NAME}"
      o: "username=${SHARE_USER},password=${SHARE_PASSWORD},vers=3.0,uid=1000,gid=1000"

이제 코드에서는 /mnt/share를 일반 디렉터리처럼 사용하면 됩니다.

이해해 둘 만한 요소는 다음과 같습니다:

APP_NAME은 플랫폼이 자동으로 제공하는 표준 변수 중 하나로, 볼륨 이름의 범위를 해당 앱으로 한정합니다.

구성 가능하게 만들기

사용자에게 제대로 된 양식이 제공되도록 — 비밀번호는 시크릿으로 마스킹된 채로 — .ironflock/env-template.yml에 플레이스홀더를 선언합니다:

SHARE_HOST:
    label: "File server (IP or hostname)"
    type: text
    defaultValue: ""
    description: "The SMB server or NAS on the device's local network."
 
SHARE_NAME:
    label: "Share name"
    type: text
    defaultValue: ""
 
SHARE_USER:
    label: "Username"
    type: text
    defaultValue: ""
 
SHARE_PASSWORD:
    label: "Password"
    type: text
    secret: true
    defaultValue: ""
 
SHARE_REV:
    label: "Storage settings revision"
    type: numeric
    defaultValue: 1
    description: "Increase by 1 whenever you change one of the settings above, then restart the app."

각 디바이스에서 사용자는 앱의 파라미터 아래에 있는 양식을 작성하고, 저장한 뒤, 앱을 재시작합니다. 파라미터를 디바이스 그룹 수준에서 설정하면 플릿 전체를 한 번에 동일한 파일 서버로 구성할 수 있습니다.

나중에 설정 변경하기

Docker는 볼륨이 처음 사용될 때 이를 생성하고 그 시점의 설정을 계속 유지합니다 — 파라미터만 수정해서는 기존 볼륨이 새 대상을 가리키게 되지 않습니다. 리비전 파라미터가 바로 이를 위한 것입니다: 공유 설정을 변경한 후 사용자는 리비전을 1 올리고 앱을 재시작합니다. 새로운 볼륨 이름 덕분에 Docker가 현재 값으로 마운트를 새로 생성합니다.

이 과정에서 파일 서버의 어떤 것도 영향을 받지 않습니다: 볼륨은 마운트 정의일 뿐입니다. 볼륨을 생성하거나, 새 리비전으로 다시 생성하거나, 앱을 제거해도 공유에 있는 파일은 절대 삭제되지 않습니다.

NFS

NFS 서버의 경우, driver_opts만 다를 뿐 동일한 패턴입니다:

volumes:
  netshare:
    name: "${APP_NAME}_share_r${SHARE_REV:-1}"
    driver: local
    driver_opts:
      type: nfs
      device: ":${SHARE_PATH}"
      o: "addr=${SHARE_HOST},nfsvers=4"

SHARE_PATH는 내보내진(export) 경로(예: /exports/production)이고, addr는 서버입니다. NFSv4(nfsvers=4)를 권장합니다 — 이 옵션 하나만으로 충분하며 디바이스에 추가 서비스도 필요하지 않습니다.

디바이스 지원

Windows 디바이스에서는 마운트가 Docker Desktop의 Linux 환경 내부에서 이루어지며, 이 환경에는 두 프로토콜 클라이언트가 모두 포함되어 있습니다 — 디바이스 LAN의 SMB 서버에 접근하는 것을 포함하여 별도의 설정 없이 바로 작동합니다. Linux 디바이스에서는 표준 배포판 커널이 프로토콜 지원을 제공하므로 설치할 패키지가 없습니다. FlockOS 지원에는 아직 출시되지 않은 운영 체제 업데이트가 필요합니다 — 필요하시면 문의해 주십시오.

마운트에는 최신 디바이스 에이전트가 필요하며, 에이전트는 자동으로 스스로 업데이트됩니다.

알아 두면 좋은 사항

• 미구성 디바이스: 파라미터가 채워지기 전까지 앱은 시작에 실패하며, 실시간 로그에 마운트 오류가 표시됩니다. 앱이 공유 없이도 실행되어야 한다면 무조건 마운트하지 마십시오 — 대신 코드에서 파라미터를 읽어 공유에 의존하는 기능을 건너뛰십시오.
• 자격 증명: 파일 서버에 이 공유에만 접근할 수 있는 전용 계정을 만들고, 이를 파라미터에 사용하십시오. 비밀번호는 플랫폼 UI에서 마스킹되지만 마운트를 수행하는 디바이스에는 전달됩니다 — 전역 관리자 자격 증명이 아니라 디바이스 로컬 자료로 취급하십시오.
• 비밀번호에 쉼표 금지: SMB 옵션은 쉼표로 구분된 문자열로 전달되므로, 쉼표가 포함된 비밀번호는 마운트를 깨뜨립니다. 공유 계정의 비밀번호를 이에 맞게 정하십시오.
• 서버 주소: IP 주소 또는 현장 DNS가 해석할 수 있는 이름을 사용하십시오. nas.local 같은 mDNS 이름은 Docker 엔진 내부에서 해석되지 않는 경우가 많습니다.
• 방화벽: 디바이스는 TCP 445(SMB) 또는 TCP 2049(NFS)로 파일 서버에 접근합니다. 세그먼트로 분리된 공장 네트워크에서는 이 경로가 열려 있는지 확인하십시오.
• 파일 소유권(SMB): 컨테이너 내부에서 파일은 마운트 옵션의 uid/gid가 소유한 것으로 나타납니다. 프로세스가 root가 아닌 사용자로 실행된다면 이를 해당 사용자로 설정하십시오. 그렇지 않으면 쓰기가 실패합니다.