서버 작업을 하다 보면 PC에 있는 파일을 서버에 올리거나, 서버에 있는 로그 파일을 PC로 받고 싶을 때가 있습니다. 파일 하나를 옮기는 정도라면 다운로드는 Winstone으로, 업로드는 간단한 웹 애플리케이션인 uploader로 했습니다. Python이 설치된 서버라면 python3 -m http.server로 웹 서버를 띄우는 방법도 있습니다.

여러 개의 파일을 주고받을 때는 FTP가 편합니다. 그런데 대부분의 FTP 서버는 설정 파일을 만들고 사용자 목록을 따로 적어야 실행됩니다. 패키지를 내려받고, 압축을 풀고, 설정 파일을 편집하는 과정을 여러 번 반복하다 보니 실행할 때 옵션만 주면 바로 뜨는 서버가 필요했습니다. 그래서 2012년에 Apache FtpServer를 감싼 실행 가능한 jar 파일을 만들어서 one-ftpserver라는 이름으로 공개했습니다.

2026년 8월에는 같은 프로그램을 Go로 다시 작성해서 2.0.0을 냈습니다. 2.0.0부터는 JVM 없이 실행 파일 하나로 배포하고, jar 안에 넣어 두었던 FTPS용 key store도 없앴습니다. 이 글은 2026년 8월에 나온 2.2.0을 기준으로 씁니다.

릴리스 페이지에서 플랫폼에 맞는 바이너리를 받습니다.

배포하는 파일은 다음의 4개입니다.

macOS에서는 go build로 직접 빌드하셔서 사용하실 수 있습니다.

아무 옵션 없이 실행하면 현재 디렉터리를 2121번 포트로 공유하고 익명 사용자(anonymous) 로그인을 받습니다.

포트, 아이디, 비밀번호, 공유할 디렉터리는 명령행에서 바로 지정합니다.

서버가 실행되면 적용된 설정과 함께, 그 설정에 맞는 클라이언트 명령을 계정 정보까지 채워서 출력합니다.

이 명령을 그대로 복사해서 다른 PC에서 실행하면 파일을 주고받을 수 있습니다.

--ssl을 주면 implicit FTPS로 동작합니다. ftps:// URL로 사용하는 방식입니다. 인증서는 서버가 시작할 때 메모리에서 만듭니다. 유효기간은 1년이고 localhost와 그 장비의 IP 주소를 담으며, 서버를 다시 띄우면 새로 만듭니다. 아무도 서명하지 않은 인증서라서 클라이언트가 검증할 방법이 없고, 그래서 서버가 출력하는 curl 명령에는 -k가 붙습니다.

이 인증서는 전송 구간을 암호화할 뿐, 서버가 누구인지는 증명하지 못합니다. 서로 아는 두 사람이 신뢰할 수 없는 네트워크를 거쳐 파일을 주고받는 상황에는 충분하지만, 모르는 사람이 접속하는 서버라면 직접 발급받은 인증서를 PEM 파일 한 쌍으로 넘기는 편이 낫습니다. 한 쌍을 넘기면 --ssl은 저절로 켜지고, 출력되는 명령에서 -k가 빠집니다.

인증서를 무료로 발급받는 방법으로는 Let’s Encrypt가 편합니다. 도메인이 가리키는 장비에서 80번 포트를 열어 두고 발급받습니다.

직접 발급받은 인증서를 쓸 때 걸리기 쉬운 부분이 세 가지 있습니다.

로그인, 파일 전송, 목록 조회, 삭제, 이름 변경을 모두 기록합니다. 기본으로는 실행한 위치에 날짜가 붙은 파일을 만듭니다.

날짜가 바뀌면 새 파일을 엽니다. 이름을 바꾸거나 지우는 처리는 하지 않으므로, 오래 띄워 둔 서버는 하루에 한 개씩 파일을 남깁니다. --log로 위치를 옮기고, off로 로그를 끕니다.

--console은 같은 내용을 터미널에도 출력합니다. 전송이 되는지 눈으로 확인하려고 띄운 서버에 씁니다.

두 옵션은 독립적입니다. --console만 주면 파일과 터미널에 함께 쓰고, --console --log=off를 주면 터미널에만 씁니다. 접속 기록은 표준 에러로 나가므로 설정 요약과 --json 출력은 표준 출력에 그대로 남습니다. 비밀번호는 로그에 남기지 않습니다. 로그인에 실패한 요청이 보낸 값도 마찬가지입니다.

파일 하나를 옮기려고 띄운 서버가 그 뒤로도 계속 떠 있을 이유는 없습니다. --timeout에 지정한 시간이 지나면 서버가 스스로 종료합니다.

passive 전송은 클라이언트가 다시 접속할 주소를 서버가 알려 주는 방식인데, 서버가 보는 주소와 클라이언트가 접근할 수 있는 주소가 다를 때가 있습니다. --publicHost로 알려 줄 주소를, --passivePorts로 방화벽에서 열거나 컨테이너에서 노출할 만큼 좁은 포트 범위를 지정합니다.

--json은 텍스트 요약 대신 같은 내용을 담은 JSON 객체 하나를 출력합니다. 주소와 계정 정보를 텍스트에서 파싱하지 않고 꺼낼 수 있습니다.

--port=0과 같이 쓰면 포트를 정하지 않고 여러 대를 동시에 띄울 수 있습니다. 각 서버가 배정받은 포트를 출력합니다.

2.0.0은 Java로 만들었던 0.1을 Go로 다시 쓴 버전입니다. 실행 방법과 옵션 형식이 함께 바뀌었습니다.

FTP 프로토콜은 ftpserverlib가 처리하고, 파일 시스템은 afero로 감쌉니다. One FTP Server가 더하는 부분은 사용자 한 명을 인증하는 driver, 실행할 때 만드는 인증서, 그리고 설정 요약 출력입니다.

부동소수점 오차는 jshell에서 간단히 확인해 볼 수 있습니다. jshell은 JDK 9부터 JDK에 포함된 대화형 실행 도구입니다. 따로 내려받을 필요 없이 JDK를 설치했다면 jshell 명령으로 바로 실행할 수 있습니다.

0.1을 열 번 더해도 1.0이 되지 않습니다.

double 리터럴 0.1에 실제로 저장된 값은 BigDecimal 생성자로 확인할 수 있습니다.

jshell 명령행에서 0.1로 입력했지만 저장된 값은 0.1보다 아주 조금 큰 다른 수입니다.

이 오차는 자바만의 문제가 아닙니다. JavaScript의 number 타입도 IEEE 754 binary64 형식을 쓰기 때문에, Chrome 개발자 도구 콘솔에서 같은 식을 입력하면 결과가 똑같습니다.

왜 이런 값이 저장되는지는 다음 절에서 double의 비트 구조를 따라가며 살펴봅니다.

IEEE 754는 여러 부동소수점 형식을 정의하는 표준입니다. 그중 자바가 쓰는 두 형식은 다음과 같습니다.

1985년에 나온 첫 표준인 IEEE 754-1985에서는 이 두 형식을 single, double이라고 불렀고, 2008년 개정판에서 binary32, binary64로 이름이 바뀌어 현행 표준인 IEEE 754-2019까지 이어집니다. 표준에는 이 외에도 binary16, binary128과 10진 형식인 decimal32, decimal64, decimal128이 들어 있습니다.

IEEE 754는 실수를 2진수 과학적 표기법으로 바꾼 다음 비트로 저장합니다. 십진수 과학적 표기법에서는 소수점을 옮겨 정수부를 1~9 사이 한 자리로 만들고, 옮긴 자릿수를 10의 지수로 나타냅니다. 예를 들어 0.001은 1.0 × 10^-3으로 씁니다. 2진수에서도 같은 원리로 2를 곱하거나 나눠서 정수부가 한 자리가 되도록, 즉 값이 1 이상 2 미만이 되도록 만듭니다. 2진수에서 0이 아닌 한 자리 숫자는 1뿐이므로, 이렇게 정규화한 결과는 언제나 ±1.가수 × 2^지수 형태가 됩니다. 예를 들어 2진수 0.011(십진수 0.375)은 1.1 × 2^-2으로 씁니다.

double (binary64)은 이렇게 정규화한 값을 64비트에 담으면서 다음 규칙을 따릅니다.

이 규칙대로 0.1을 저장한 결과가 아래 그림입니다. 64비트가 부호 1비트, 지수 11비트, 가수 52비트로 나뉘어 있습니다.

그림 아래쪽의 변환 과정을 따라가 보겠습니다. 0.1에 2를 거듭 곱해 보면 0.2, 0.4, 0.8을 거쳐 네 번째에 1.6이 되어 처음으로 1 이상 2 미만 구간에 들어옵니다. 2를 네 번 곱해서 1.6이 되었으니 거꾸로 0.1 = 1.6 ÷ 2⁴ = 1.6 × 2^-4입니다. 따라서 부호 비트는 0, 지수부는 -4 + 1023 = 1019가 됩니다. 문제는 가수입니다. 0.6을 2진수로 바꾸면 0.1001 1001 1001…처럼 1001이 무한히 반복되어 끝나지 않습니다. 52비트 안에 담으려면 반올림할 수밖에 없고, 그 결과 0.1이 아니라 0.1보다 아주 조금 큰 수가 저장됩니다. 앞에서 new BigDecimal(0.1)로 확인한 0.1000000000000000055511151231257827021181583404541015625가 바로 이 반올림된 값입니다.

모든 소수에서 오차가 생기는 것은 아닙니다. 0.5(1/2), 0.25(1/4), 0.75(3/4)처럼 분모가 2의 거듭제곱인 소수는 유한한 2진 소수가 되므로 정확하게 저장됩니다. 반면 0.1 = 1/10처럼 분모에 5가 끼어 있는 십진 소수는 2진수로는 무한히 반복되는 소수가 되어 반올림 오차를 피할 수 없습니다. 표준을 더 자세히 알고 싶다면 IEEE 754 위키백과 문서를 참고할 수 있습니다.

과학 실험의 데이터처럼 근삿값을 다루는 영역에서는 이런 오차가 용인되기도 합니다. 그러나 소수점 단위의 오차가 치명적인 버그를 만들 수 있는 분야도 있습니다. 이런 오차가 실제 장애로 이어진 국내와 해외 사례를 하나씩 살펴보겠습니다.

double형 연산에서 생기는 오차를 피하는 두 가지 방법을 소개합니다.

우선 계산 정밀도가 중요한 모듈에서 double형은 반환형이나 메서드 파라미터 타입으로 쓰지 않는다는 규칙은 최소한도로 추구할만 합니다. 이를 어떤 타입으로 대체할지는 앞에서 말한 BigDecimal vs '정수형 최소 단위’의 선택지가 있습니다. 성능과 코드의 간결함은 long이 낫습니다. BigDecimal은 개발자의 실수를 예방하는 측면에서는 유리합니다.

앞에서 언급한 'Effective Java' 아이템 60도 같은 기준으로 선택을 정리해 두었습니다. 소수점 추적을 시스템에 맡기고 반올림 방식까지 고르고 싶다면, 기본 타입보다 쓰기 불편하고 느리다는 비용을 감수하고 BigDecimal을 쓰라는 것이 이 항목의 결론입니다. 반대로 성능이 중요하고 소수점을 직접 추적할 수 있다면 int나 long을 쓰라는 대안도 함께 제시하는데, 앞 절에서 본 정수형 최소 단위 계산과 같은 방법입니다. 값이 십진수로 아홉 자리를 넘지 않으면 int, 열여덟 자리를 넘지 않으면 long, 그보다 크면 BigDecimal을 쓰라는 자릿수 기준도 덧붙입니다.

Chronicle Software의 Peter Lawrey는 If BigDecimal is the answer, it must have been a strange question에서 BigDecimal의 단점을 이렇게 꼽습니다.

Lawrey의 결론은 "double의 반올림을 다루는 법을 모르거나 프로젝트 표준이 BigDecimal을 강제한다면 BigDecimal을 쓰되, 선택할 수 있다면 BigDecimal이 당연히 옳다고 가정하지는 말라"는 것입니다. 지연 시간에 민감한 금융 시스템 중에는 BigDecimal 없이 만들어진 시스템도 많이 돌아가고 있다는 점도 근거로 듭니다.

정수형 최소 단위 계산은 시스템 자원을 적게 쓴다는 장점이 있습니다. long 타입의 값은 객체를 만들지 않고, 연산도 CPU의 정수 연산으로 끝납니다. 대신 개발자가 정확한 연산을 더 많이 의식해야 합니다. 반올림 규칙을 정해야 한다는 점은 BigDecimal도 마찬가지라 차이가 아닙니다. 차이는 그 규칙을 빠뜨렸을 때 나타납니다. BigDecimal은 십진수로 끝나지 않는 나눗셈에서 반올림 방식을 빠뜨리면 앞에서 본 것처럼 예외를 던지지만, long 나눗셈은 소수점 이하를 경고 없이 버립니다. 최소 단위를 무엇으로 볼지를 시스템 전체가 같은 규칙으로 지켜야 한다는 부담도 BigDecimal에는 없습니다. 기본 산술 연산자로 계산하다 보니, calculate() 예제의 amount * rate * 0.01처럼 중간에 부동소수점이 섞여도 컴파일러가 막지 않습니다.

지금까지의 내용을 정리하면 다음과 같습니다.

어떤 타입을 쓸지 정하고 실제 코드에 반영하는 데 가장 중요한 것은 팀 구성원이 이해하기 쉬운 단순한 규칙으로 명시하는 것입니다. 시스템의 담당 개발자는 계속 바뀔 수 있습니다. 모든 사람이 이 글에서 다룬 오차가 생기는 원리까지 이해하고 있다고 전제하기는 어렵습니다. 규칙이 명확하고 단순하면 새로 투입된 개발자도 동일하게 따라갈 가능성이 높아집니다. 그 결과로 전체 모듈에서 소수점 이하 연산을 다루는 일관성이 지켜지고, 치명적인 오차를 만드는 코드가 들어올 가능성도 줄어듭니다. 따라서 정하려는 규칙을 간결하고 명확하게 문서로 적을 수 있는지도 판단 기준으로 삼아 봤으면 합니다.

규칙을 정하고 나면 그와 어긋나는 기존 코드까지도 고쳐야 앞으로도 일관성이 유지됩니다. 그런데 이미 잘 돌아가고 있는 데다 금액을 직접 다루는 코드는 고치기가 무섭습니다. 그래서 한번 자리 잡은 방식을 바꾸지 않는 경우도 많습니다. 그런 상황에 대비해서도 금액처럼 민감한 수치를 다루는 로직은 쉽게 테스트할 수 있는 구조로 분리해야 합니다. 테스트하기 쉬운 구조라면 소수점 오차뿐 아니라 새로 추가하는 코드의 논리 오류도 이른 시점에 감지할 수 있습니다.

앞에서 본 두 방법은 수를 어떤 형태로 담을지의 선택입니다. 그 위에서 금액, 시간, 물리량처럼 단위가 붙는 값을 전용 타입으로 감싸는 도메인 특화 라이브러리도 있습니다. 이런 라이브러리도 안에서는 결국 BigDecimal이나 정수형 최소 단위 중 하나로 수를 담습니다. 대표적인 예로 Java Money를 살펴봅니다.

BTrace는 실행 중인 JVM에 붙어서(attach) 지정한 메서드에 계측 코드를 끼워 넣는 동적 트레이싱 도구입니다. 애플리케이션 소스를 수정하거나 서버를 재시작하지 않아도 됩니다. 추적할 지점과 수집할 값은 Java 문법으로 작성한 스크립트에 애너테이션으로 선언합니다.

이 블로그에서는 예전에 Btrace로 DBCP의 connection정보를 모니터링 하기에서 소개한 적이 있습니다. 이번 예제는 같은 도구로 Connection pool 대신 JDBC 드라이버 내부를 들여다봅니다.

ConnectionMonitor.java는 MySQL Connector/J 5.1의 내부 메서드 4개를 추적합니다.

각 메서드의 호출 횟수와 평균 실행 시간을 모으면, 드라이버 튜닝 옵션(cachePrepStmts, useLocalSessionState 등)을 바꿨을 때 내부 호출이 실제로 줄어드는지 수치로 확인할 수 있습니다. 애플리케이션 코드 계층에서는 보이지 않는 드라이버 내부의 동작이라서 BTrace 같은 도구가 유용합니다.

핵심 부분만 옮기면 아래와 같습니다.

사용한 BTrace 기능은 세 가지입니다.

저장소에는 `PrintQuery.java`도 있는데, 실행 쿼리 출력용으로 만들려다 만 것인지 `ConnectionMonitor.java`와 내용이 같은 사본입니다.

이전 BTrace 글에서 소개했던 DBCP 모니터링 스크립트들(DbcpMonitor.java, DbcpMonitorSimple.java, DbcpActiveConnectionMonitor.java)도 gist에서 이 저장소로 옮겨 함께 두었습니다. CUBRID 드라이버와 Spring 서블릿을 추적하던 CubridConnectionMonitor.java, `DaoMonitor.java`도 같은 gist에서 옮긴 스크립트입니다.

BTrace 클라이언트로 대상 JVM의 pid를 지정해서 실행합니다.

측정을 끝내고 싶을 때 클라이언트에서 Ctrl+C를 누르면 이벤트 전송 여부를 묻는 메뉴가 나옵니다. 이벤트를 보내면 @OnEvent 핸들러가 실행되어 아래처럼 요약이 출력됩니다.

pom.xml에 선언한 btrace-client 의존성은 빌드용이 아니라 IDE에서 BTrace API의 자동완성과 컴파일 검증을 받기 위한 것입니다. 실제 실행은 위처럼 BTrace 클라이언트가 스크립트 파일을 직접 받아서 처리합니다.

이 스크립트는 BTrace 1.2와 Connector/J 5.1, JDK 6~8 시절에 작성했습니다. 최신 LTS인 JDK 25 기준으로는 상황이 꽤 다릅니다.

이 포스트는 Claude Code와 정상혁이 함께 작성했습니다.