ivada-infra/DOCS
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync local updates (2026-03-07)

Browse Source
This commit is contained in:
happybell80 2026-03-07 17:01:46 +09:00
parent 1d53458143
commit 80d58eda79
7 changed files with 394 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
01_Terminology/100_인프라_용어집.md Normal file
View File

@ -0,0 +1,41 @@
# 100. 인프라 용어집
인프라 문서에서 자주 나오는 약어와 운영 용어를 짧게 정리합니다.
## 읽는 방법
- 약어나 낯선 용어를 본문에 쓸 때는 첫 등장 시 이 문서 기준으로 풀어쓴다.
- 같은 뜻의 용어가 여러 문서에 섞이면 이 문서 표기로 통일한다.
- 설명 없이 쓰면 오해가 생기는 용어는 먼저 이 문서에 등록한다.
## 용어
### SMB (Server Message Block)
윈도우 파일 공유에 많이 쓰는 네트워크 파일 공유 방식입니다. NAS를 폴더처럼 붙여 쓰는 CIFS 마운트의 기반 프로토콜로 보면 됩니다.
### CIFS (Common Internet File System)
SMB 계열 파일 공유 방식으로, 이 서버에서는 내부 NAS를 `/mnt/nas`에 마운트할 때 사용합니다.
### NAS (Network Attached Storage)
네트워크로 붙는 저장장치입니다. 현재 내부 NAS는 백업, 로그 아카이브, 산출물 보관의 기준 저장소입니다.
### DSM (DiskStation Manager)
시놀로지 NAS의 기본 웹 관리자 화면과 그 뒤의 API 체계입니다. 쉽게 말해 브라우저로 여는 NAS 운영 화면입니다. 외부 NAS에서는 파일 공유 직접 접근이 막혀 있어서 이 웹 방식으로 파일 접근을 확인했습니다.
### API (Application Programming Interface)
시스템끼리 기능을 호출하는 연결 방식입니다. 이번 문맥에서는 외부 NAS 파일을 DSM API로 내려받는 경로를 뜻합니다.
### SSOT (Single Source of Truth)
같은 정보를 여러 곳에 중복 관리하지 않고, 한 군데를 기준 원본으로 삼는 원칙입니다. IP, 마운트 경로, 계정 정보는 SSOT가 깨지면 운영 사고로 이어집니다.
### SSHFS (SSH Filesystem)
SSH로 원격 디렉터리를 로컬 폴더처럼 붙여 쓰는 방식입니다. 현재 24 서버 계열 경로 `/mnt/51123data`, `/mnt/51123logs` 설명에서 자주 나옵니다.
### 마운트 (Mount)
원격 저장소나 다른 디스크를 현재 서버의 특정 경로에 연결해, 로컬 폴더처럼 보이게 만드는 작업입니다.
### 내부 NAS
우리 네트워크 안에 있는 NAS입니다. 현재 기준 주소는 `192.168.0.101`입니다.
### 외부 NAS
우리 내부망 밖에서 접속하는 NAS입니다. 현재 문서에서는 `sigongipc.synology.me`로 접근하는 컴퍼니엑스 측 NAS를 뜻합니다.

42
README.md
View File

@ -13,34 +13,28 @@
## 문서 구조
1. `00_Philosophy/`
- 인프라 프로젝트가 왜 존재하는지, 무엇을 지켜야 하는지, 무엇을 금지하는지 정의합니다.
- 반복 검증 후에도 바뀌기 어려운 기준만 둡니다.
- 인프라 프로젝트의 정체성, 원칙, 가드레일 문서
2. `02_Architecture/`
- 23/24/NAS를 중심으로 한 실제 구성 요소, 역할 분리, 트래픽/데이터/운영 구조를 정리합니다.
- 철학을 운영 가능한 구조로 번역한 계층입니다.
2. `01_Terminology/`
- 인프라 운영에서 반복되는 약어와 핵심 용어 정리
3. `journey/`
- 리서치, 계획, 트러블슈팅, 워크로그를 기록합니다.
- 실행 중 사실, 조치, 검증 결과는 여기만 기록합니다.
3. `02_Architecture/`
- 23/24/NAS를 중심으로 한 구성 요소와 운영 구조 문서
## 인프라 프로젝트에 맞춘 구조 선택 이유
4. `journey/`
- 리서치, 계획, 트러블슈팅, 워크로그 문서
- 일반 서비스 프로젝트처럼 `제품 기획`보다 `지속성 있는 운영 기반`이 중심입니다.
- 따라서 `철학 -> 구조 -> 실행 기록`의 3층이 가장 적합합니다.
- 전략/로드맵은 필요 시 `journey/plans`에서 운영 계획으로 다루고, 고정 철학은 `00_Philosophy`로 승격합니다.
## 먼저 보면 좋은 문서
- `01_Terminology/100_인프라_용어집.md`
- `00_Philosophy/00_IDENTITY/Infra_Project_Identity.md`
## 빠른 읽기 순서
1. `00_Philosophy/00_IDENTITY/Infra_Project_Identity.md`
2. `00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md`
3. `00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md`
4. `02_Architecture/Infrastructure_Project_Structure.md`
5. `journey/research/260307_value_기준_인프라철학문서_구조초안.md`
6. `journey/README.md`
## 문서 운영 규칙
- `00_Philosophy/`는 고정 기준만 둡니다.
- 실제 장애, 변경, 점검, 복구 기록은 `journey/`에만 둡니다.
- `0_VALUE` 공통 원칙과 충돌하면 `0_VALUE`를 우선합니다.
1. `01_Terminology/100_인프라_용어집.md`
2. `00_Philosophy/00_IDENTITY/Infra_Project_Identity.md`
3. `00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md`
4. `00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md`
5. `02_Architecture/Infrastructure_Project_Structure.md`
6. `journey/research/260307_value_기준_인프라철학문서_구조초안.md`
7. `journey/README.md`

4
journey/README.md
View File

@ -20,3 +20,7 @@
## 현재 문서
- [23서버 워크스페이스 인프라 구조정리 이슈](./troubleshooting/260307_23서버_워크스페이스_인프라_구조정리_이슈.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 파일 동기화 아이디어](./ideas/260307_external_nas_companyx_sync_아이디어.md)
- [컴퍼니엑스 직원용 모바일 파일 포털 아이디어](./ideas/260307_companyx_mobile_file_portal_아이디어.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치](./research/260307_external_nas_companyx_sync_research.md)
- [컴퍼니엑스 직원용 모바일 파일 포털 리서치](./research/260307_companyx_mobile_file_portal_research.md)

59
journey/ideas/260307_companyx_mobile_file_portal_아이디어.md Normal file
View File

@ -0,0 +1,59 @@
# 260307 컴퍼니엑스 직원용 모바일 파일 포털 아이디어
tags: [companyx, mobile, file-portal, ideas]
상위 원칙:
- [Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
## 문제
- 현재 NAS 기본 관리자 화면은 데스크톱형이라 휴대폰에서 쓰기 불편하다.
- 컴퍼니엑스 직원이 필요한 것은 NAS 전체 관리자 권한이 아니라, 필요한 파일을 보고 내려받고 올리는 간단한 화면일 가능성이 높다.
- 따라서 “기본 관리자 화면 개선”보다 “직원용 파일 포털 별도 제공”이 더 현실적이다.
## 목표
- 내부 NAS에 들어온 컴퍼니엑스 파일을 모바일에서도 쉽게 찾고 열 수 있게 한다.
- 관리자 화면을 그대로 노출하지 않고, 직원용 기능만 제한적으로 제공한다.
## 가능한 방향
### 1. 기존 오픈소스 파일 포털 도입
- 모바일 친화 파일 브라우저를 앞단에 붙인다.
- 장점: 빠르게 검증 가능
- 단점: 권한 모델과 UI를 우리 상황에 맞게 조정해야 할 수 있다
### 2. 내부 NAS 파일 API 위에 전용 모바일 웹 제작
- 필요한 기능만 가진 전용 화면을 만든다.
- 장점: 컴퍼니엑스 업무 흐름에 맞출 수 있다
- 단점: 구현과 유지보수 비용이 든다
### 3. 혼합 방식
- 1차는 오픈소스 도구로 빠르게 써 보고
- 2차는 실제 사용 패턴이 모이면 전용 화면으로 전환한다
## 권장 방향
- 1차는 오픈소스 후보 검증
- 2차는 직원이 실제로 자주 쓰는 기능을 좁힌 뒤 전용 모바일 웹 판단
## 먼저 확인할 것
1. 직원이 필요한 기능이 조회만인지, 업로드도 필요한지
2. 폴더 권한을 사람별로 나눠야 하는지
3. 모바일에서 미리보기할 파일 유형이 무엇인지
4. 사내망 전용인지, 외부 접속도 필요한지
## 연결 문서
- [260307_companyx_mobile_file_portal_research.md](../research/260307_companyx_mobile_file_portal_research.md)
- [260307_external_nas_companyx_sync_research.md](../research/260307_external_nas_companyx_sync_research.md)
## 관련 문서
- [100_인프라_용어집.md](../../01_Terminology/100_인프라_용어집.md)

71
journey/ideas/260307_external_nas_companyx_sync_아이디어.md Normal file
View File

@ -0,0 +1,71 @@
# 260307 외부 NAS -> 내부 NAS 컴퍼니엑스 파일 동기화 아이디어
tags: [nas, companyx, sync, ideas]
상위 원칙:
- [Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
## 목적
- 컴퍼니엑스 외부 NAS의 파일을 우리 내부 NAS로 안정적으로 가져오는 운영 방안을 정리한다.
- 실시간 미러링이 아니라, 운영 가능한 단방향 동기화 구조를 먼저 정한다.
## 현재 확인된 사실
- 외부 NAS는 `sigongipc.synology.me:5000/5001`의 Synology DSM 경로로 접근 가능하다.
- 외부 SMB 직접 접근은 타임아웃으로 막혀 있다.
- 파일 1건 다운로드 후 내부 NAS 저장과 SHA256 일치가 확인됐다.
- 내부 NAS는 `192.168.0.101`이며 51123의 `/mnt/nas`로 실마운트되어 있다.
## 가능한 방식
### 1. 주기 배치 동기화
- 일정 주기마다 외부 NAS 목록을 조회하고 새 파일만 내부 NAS로 내려받는다.
- 장점: 구현이 단순하고 운영 리스크가 낮다.
- 단점: 실시간은 아니다.
### 2. 폴더 단위 스냅샷 동기화
- 컴퍼니엑스의 핵심 폴더만 골라 정해진 시각에 통째로 동기화한다.
- 장점: 우선순위 관리가 쉽다.
- 단점: 큰 폴더는 시간이 오래 걸릴 수 있다.
### 3. 매니페스트 기반 증분 동기화
- 외부 NAS 파일 목록, 크기, 수정시각, 해시를 기록한 매니페스트를 내부에 두고 변경분만 반영한다.
- 장점: 중복 다운로드를 줄일 수 있다.
- 단점: 구현과 검증이 더 복잡하다.
## 권장 방향
- 1차는 `주기 배치 동기화`로 시작한다.
- 구조가 안정되면 `매니페스트 기반 증분 동기화`로 확장한다.
- 초기에 중요한 것은 속도보다 설명 가능성과 재현 가능성이다.
## 현재 실측을 반영한 운영 아이디어
- 문서/엑셀/PDF 위주 경로는 `5분~10분 간격 증분 동기화` 후보로 볼 수 있다.
- 사진처럼 파일 수가 많은 폴더는 낮 시간 `15분~30분 간격 증분`, 야간 `1회 전체 스캔`이 더 안전하다.
- 초기 운영은 “핵심 폴더 우선 동기화 + 야간 전체 점검” 구조가 적절하다.
- 인증서 만료 때문에 HTTPS 검증 우회(`-k`)가 필요한 상태이므로, 장기 운영 전 인증서 처리 정책을 정해야 한다.
## 먼저 정해야 할 정책
1. 대상 루트: 컴퍼니엑스 전체인지, 특정 상위 폴더만 우선인지
2. 주기: 매일 1회 전체 + 낮 시간 변경분 추적 여부
3. 충돌 처리: 동일 파일명, 수정시각 역전, 삭제 전파 여부
4. 검증 방식: 파일 크기만 볼지, SHA256까지 볼지
5. 기록 방식: 실행 로그, 실패 목록, 마지막 성공 시각을 어디에 남길지
## 다음 문서
- 리서치: [260307_external_nas_companyx_sync_research.md](../research/260307_external_nas_companyx_sync_research.md)
- 기존 프로브: [260307_external_nas_to_internal_nas_sync_probe.md](../../260307_external_nas_to_internal_nas_sync_probe.md)
## 관련 문서
- [100_인프라_용어집.md](../../01_Terminology/100_인프라_용어집.md)
- [260307_companyx_mobile_file_portal_아이디어.md](./260307_companyx_mobile_file_portal_아이디어.md)

85
journey/research/260307_companyx_mobile_file_portal_research.md Normal file
View File

@ -0,0 +1,85 @@
# 260307 컴퍼니엑스 직원용 모바일 파일 포털 리서치
tags: [companyx, mobile, file-portal, research]
상위 원칙:
- [Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
## 목적
- 컴퍼니엑스 직원이 모바일이나 일반 웹에서 파일을 쉽게 볼 수 있는 대안 화면이 가능한지 확인한다.
- NAS 기본 관리자 화면을 그대로 쓰지 않고, 더 쉬운 파일 화면을 제공하는 방법을 조사한다.
## 확인된 사실
- 시놀로지 기본 관리자 화면은 브라우저 안에서 바탕화면처럼 동작하는 데스크톱형 구조다.
- 모바일 친화 관리자 웹이라기보다, PC 관리 효율 중심 화면에 가깝다.
- 외부 NAS 파일을 내부 NAS로 가져오는 경로는 이미 검증 중이다.
## 핵심 질문
1. 직원에게 관리자 화면이 필요한가
2. 아니면 파일 조회/다운로드/업로드만 되는 단순 화면이면 충분한가
3. 기존 오픈소스를 붙이는 것이 빠른가
4. 전용 모바일 웹을 만드는 것이 장기적으로 맞는가
## 조사 결과
### 1. 공식 파일 API 사용 가능성
- 시놀로지는 파일 목록 조회, 다운로드, 업로드 등에 사용할 수 있는 공식 파일 API를 제공한다.
- 따라서 내부 NAS 파일을 읽는 별도 웹 화면을 기술적으로 만드는 것은 가능하다.
### 2. 오픈소스 후보
#### Filestash
- 모바일 친화 파일 포털 성격
- 여러 스토리지 백엔드를 연결하는 방식
- 빠른 프로토타입 후보
#### FileRise
- 반응형 웹 파일 관리자 성격
- 파일 조회 중심 검토 후보
#### nico.drive
- 모바일 화면을 의식한 WebDAV 기반 파일 화면
- 파일 뷰어/브라우저 관점에서 참고 가치가 있다
#### linuxforphp/filebrowser
- 단순 웹 파일 브라우저
- 구조가 단순해 빠른 검토에 적합하다
## 해석
- “NAS 관리자 화면을 모바일에 맞게 다시 만든다”보다
- “직원용 파일 포털을 따로 만든다”가 더 현실적이다.
- 즉 문제의 본질은 저장장치 관리가 아니라 파일 접근 경험이다.
- 그래서 관리자 콘솔 대체품보다 파일 포털 도구를 먼저 보는 것이 맞다.
## 권장 검증 순서
1. 직원이 필요한 최소 기능 정의
- 조회, 검색, 다운로드, 업로드, 미리보기 여부
2. 오픈소스 1개 빠른 설치 검증
- 모바일 브라우저에서 실제 사용성 확인
3. 권한/보안 확인
- 폴더 제한, 로그인 방식, 외부 공개 범위 점검
4. 전용 개발 필요성 판단
- 오픈소스로 충분한지, 우리 전용 화면이 필요한지 결정
## 현재 결론
- 직원용 모바일 파일 화면은 가능하다.
- 기본 관리자 화면을 그대로 쓰는 것보다 별도 파일 포털 방식이 맞다.
- 다음 단계는 오픈소스 후보 1개를 골라 실제 모바일 사용성을 검증하는 것이다.
## 관련 문서
- [260307_companyx_mobile_file_portal_아이디어.md](../ideas/260307_companyx_mobile_file_portal_아이디어.md)
- [260307_external_nas_companyx_sync_research.md](./260307_external_nas_companyx_sync_research.md)

116
journey/research/260307_external_nas_companyx_sync_research.md Normal file
View File

@ -0,0 +1,116 @@
# 260307 외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치
tags: [nas, companyx, sync, research]
상위 원칙:
- [Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
## 목적
- 컴퍼니엑스 외부 NAS 파일을 내부 NAS로 옮기는 운영 경로를 검증한다.
- 자동 동기화 스크립트를 만들기 전에 필요한 사실과 실험 항목을 정리한다.
## 현재 기준
- 외부 NAS 접근 경로: 시놀로지 기본 웹 관리자 API
- 내부 저장 경로: 51123의 `/mnt/nas`
- 내부 NAS 기준 주소: `192.168.0.101`
- 스크립트 저장소: `infra/scripts`
## 이미 검증된 사실
1. 외부 NAS DSM 로그인 가능
2. 외부 NAS 파일 1건 다운로드 가능
3. 내부 NAS 저장 가능
4. 저장 후 SHA256 일치 확인
5. 외부 NAS 폴더 구조 일부를 내부 NAS에 미러링 가능
관련 근거:
- [260307_external_nas_to_internal_nas_sync_probe.md](../../260307_external_nas_to_internal_nas_sync_probe.md)
## 2026-03-07 실측 결과
실행 스크립트:
- `infra/scripts/bin/companyx_external_nas_sync_probe.sh`
실행 시각:
- 2026-03-07 16:22 KST
테스트 저장 경로:
- `/mnt/nas/backup/current/external-nas-timing-test/20260307_162237`
측정값:
1. DSM 로그인
- 약 `0.683초`
2. 상위 폴더 목록 조회
- 대상: `/6.Company X`
- 결과: `16개 엔트리`
- 약 `0.067초`
3. 사진 하위 폴더 목록 조회
- 대상: `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`
- 결과: `20개 엔트리`
- 약 `0.061초`
4. 샘플 파일 다운로드 및 내부 NAS 저장
- `Thumbs.db` `12,288B`: 약 `0.094초`
- `2410_투자기업 DB_컴퍼니엑스_LP추가, 컨택포인트 추가.xlsx` `151,832B`: 약 `0.103초`
- `KakaoTalk_20220322_121550595_03.jpg` `457,889B`: 약 `0.121초`
- `221028_회사소개서_디지털용.pdf` `20,147,273B`: 약 `0.571초`
관찰:
- 이 시점 실측에서는 대략 `20MB 파일 1개도 1초 이내`에 내부 NAS까지 저장됐다.
- 병목은 현재 테스트 범위에서는 내부 NAS 쓰기보다 외부 DSM 응답과 전송 구간으로 보인다.
- HTTPS 인증서는 만료 상태라 현재 스크립트는 `-k` 옵션으로 우회하고 있다. 운영 자동화 전 인증서 정리 여부를 판단해야 한다.
보수적 해석:
- “문서 파일 위주” 폴더는 `5분~10분 간격 증분 동기화`도 현실적으로 가능해 보인다.
- 다만 사진 대량 폴더나 전체 재귀 동기화는 파일 수가 많아질수록 API 호출 수가 늘어나므로, 지금 수치만으로 전체 완료 시간을 단정할 수는 없다.
- 따라서 다음 검증은 “샘플 폴더 1개 전체 동기화”와 “같은 작업 재실행 시 중복 건너뛰기”다.
## 이번 리서치에서 확인할 항목
1. 외부 NAS에서 디렉터리 목록을 안정적으로 재귀 조회할 수 있는가
2. 다운로드 단위를 파일별로 관리할 때 속도와 실패 복구가 충분한가
3. 수정시각과 크기만으로 증분 동기화가 가능한가
4. 해시 검증을 전건에 적용할지 샘플 검증으로 줄일지
5. 실패 파일 재시도와 중단 지점을 어떻게 기록할지
## 실험 순서
### 1. 목록 조회 실험
- 컴퍼니엑스 상위 폴더 목록 조회
- 하위 폴더 재귀 조회 가능 여부 확인
- 파일 수, 폴더 수, 메타데이터 제공 범위 확인
### 2. 샘플 동기화 실험
- 작은 폴더 1개를 골라 내부 NAS로 동기화
- 다운로드 시간, 저장 시간, 재실행 시 중복 처리 확인
### 3. 검증 실험
- 파일 크기, 수정시각, SHA256 비교 기준 정리
- 실패 파일 재시도 방식 기록
## 예상 산출물
1. `infra/scripts/bin/companyx_external_nas_sync_probe.sh` 개선본
2. 동기화 정책 초안 문서
3. 운영 주기 제안
4. 실패 처리 기준
## 보수적 결론
- 현재 구조로 단방향 동기화는 가능성이 높다.
- 다만 아직 자동 운영 주기와 증분 처리 기준은 검증되지 않았다.
- 따라서 다음 단계는 “전체 동기화 구현”이 아니라 “목록 조회 + 샘플 폴더 동기화 + 재실행 검증”이다.
## 관련 문서
- [260307_external_nas_companyx_sync_아이디어.md](../ideas/260307_external_nas_companyx_sync_아이디어.md)
- [260307_companyx_mobile_file_portal_research.md](./260307_companyx_mobile_file_portal_research.md)