做小生意的朋友應(yīng)該都懂一個痛貨沒多少賬特別亂。倉庫角落里堆著幾箱快過期的A貨系統(tǒng)里卻顯示還有三十件前臺剛賣完最后一件B款采購那邊又下單買了二十件。這種庫存失控的場面我見過太多次了。后來我把庫存管理從Excel里搬出來換成了自托管的OpenStock用Docker在自己的服務(wù)器上跑起來所有記錄全部自己掌控整個流程才真正順了。OpenStock是一個典型的開源自托管庫存管理系統(tǒng)它解決的就是進(jìn)銷存里最核心的“賬實相符”問題商品檔案、入庫出庫、庫存變動、供應(yīng)商和客戶往來全部在一套系統(tǒng)里閉環(huán)。你在瀏覽器里打開一個頁面就能看到當(dāng)前的實時庫存、最近一段時間的出入庫流水以及哪些商品正在往低庫存紅線逼近。它適合小微型零售店、電商賣家、做貿(mào)易的個體戶也適合技術(shù)愛好者想趁機(jī)把Docker、PostgreSQL、Nginx這類常見基礎(chǔ)設(shè)施串起來練手的人。這篇文章不是讓你去看官方文檔干啃而是按我實際搭建的順序把環(huán)境準(zhǔn)備、容器編排、初始配置、運(yùn)行維護(hù)這幾個環(huán)節(jié)完整走一遍。我會把每一步的“為什么這么做”也一并講清楚——比如為什么不建議直接裸裝依賴、為什么數(shù)據(jù)庫要單獨掛載卷、為什么上傳圖片目錄要做持久化——這些是文檔里不會寫、只有真正跑過幾輪才總結(jié)得出來的東西。1. OpenStock的整體設(shè)計思路與選型考量OpenStock我用了不短的時間先說它的設(shè)計思路。項目的技術(shù)棧是典型的前后端分離后端用某個輕量級Python框架提供REST API前端是獨立構(gòu)建的SPA靜態(tài)頁面數(shù)據(jù)庫默認(rèn)走PostgreSQL。整個項目通過Docker Compose組織服務(wù)一條docker compose up -d就能把API、前端資源、數(shù)據(jù)庫三件套拉起來。1.1 為什么選Docker Compose而不是直接部署如果你只是想在本機(jī)或一臺VPS上跑通最簡單粗暴的方式當(dāng)然是在系統(tǒng)里裝Python運(yùn)行時、裝PostgreSQL、裝Nginx再手動配虛擬環(huán)境。但這里有個現(xiàn)實問題Python依賴的版本沖突和系統(tǒng)庫缺失足以勸退新手而數(shù)據(jù)庫升級、遷移、備份這些操作裸裝環(huán)境下也要多花好幾倍的時間去維護(hù)。用Docker Compose的好處是把“部署環(huán)境”這件事從“部署業(yè)務(wù)系統(tǒng)”里剝離掉了。Compose文件里聲明好三個服務(wù)每臺機(jī)器執(zhí)行同一條命令得到的環(huán)境就是一致的。我在自己的服務(wù)器上重裝過一次系統(tǒng)之前裸裝的環(huán)境里跑了好幾個Python項目恢復(fù)OpenStock時直接在/opt/openstock目錄下重新執(zhí)行了docker compose up -d五分鐘后服務(wù)全部在線數(shù)據(jù)因為用的是宿主機(jī)掛載卷一點沒丟。就沖這點Compose方案直接勝出。1.2 核心模塊拆解商品、單據(jù)、庫存的閉環(huán)從業(yè)務(wù)角度看OpenStock的設(shè)計邏輯很規(guī)整它圍繞“進(jìn)-銷-存”這條主線拆出了幾塊核心功能商品管理維護(hù)SKU編碼、名稱、分類、單位、預(yù)警庫存閾值、零售價與成本價。入庫管理包含采購入庫、退貨入庫、盤盈入庫等正向流程生成入庫單并自動增加庫存。出庫管理包含銷售出庫、領(lǐng)用出庫、盤虧出庫等負(fù)向流程生成出庫單并自動扣減庫存。庫存查詢實時匯總各商品在庫數(shù)量支持按分類、按關(guān)鍵詞篩選。供應(yīng)商/客戶管理維護(hù)往來單位信息單據(jù)創(chuàng)建時直接關(guān)聯(lián)。報表統(tǒng)計按時間段匯總出入庫總量、庫存金額、低庫存清單。這個模塊劃分沒有什么炫技的地方但它有一個我很認(rèn)可的點——所有庫存變動都留有單據(jù)軌跡。就是說任何一筆數(shù)量變化都不是直接在庫存數(shù)字上改而是要先建一張入庫單或出庫單系統(tǒng)自動去更新庫存。這個設(shè)計讓“追責(zé)”變得非常容易哪一天庫存對不上去流水列表里按日期篩一下是哪個操作、哪張單子、誰做的一查便知。比起在Excel里手動改數(shù)字這是質(zhì)的飛躍。1.3 我對這套設(shè)計的評價說點掏心窩的看法。OpenStock不是一個功能堆得特別滿的項目它沒有多倉庫管理也沒有復(fù)雜的BOM拆裝邏輯做不了生產(chǎn)工單也管不了批次序列號。但正因為克制的功能邊界換來的是簡單、清晰、容易上手。如果你只有1到2個倉庫不涉及批次管理它絕對夠用你在小本買賣階段就用這套系統(tǒng)去理解“進(jìn)銷存”的邏輯以后換再復(fù)雜的ERP底層思路也是一模一樣的。2. 搭建前的環(huán)境準(zhǔn)備與版本選擇正式動手之前先把環(huán)境參數(shù)定下來。這塊我會把硬件要求、系統(tǒng)建議、依賴組件這幾塊講清楚因為這是整個搭建過程里最容易出岔子也最容易被忽略的部分。2.1 服務(wù)器要求實際跑起來需要多大配置OpenStock本身不是重量級應(yīng)用它的資源占用大頭在PostgreSQL和前端靜態(tài)資源服務(wù)上。我實測下來一臺1核1G的小內(nèi)存VPS完全可以跑只是數(shù)據(jù)庫啟動時稍慢一點日常操作沒什么卡頓感。如果是自己家里的舊電腦、樹莓派4B或者NAS的Docker套件也都能勝任。建議配置參考如下項目最低要求推薦配置CPU1核心2核心內(nèi)存1GB2GB磁盤10GB20GB及以上系統(tǒng)Debian 11/Ubuntu 20.04Debian 12/Ubuntu 22.04Docker20.1024.0Docker Composev2v2磁盤這塊多說一句不要只看系統(tǒng)盤默認(rèn)大小。如果你打算上傳商品圖片圖片是直接落在掛載卷里的時間長了會占不少空間。我自己的數(shù)據(jù)目錄三個月跑了4G多這里還不算PostgreSQL的數(shù)據(jù)庫文件。所以磁盤建議留足余量別卡著最低配。2.2 Docker與Compose的正確安裝方式如果你服務(wù)器上還沒有Docker別用系統(tǒng)自帶的舊版本直接用官方安裝腳本最省心。curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo systemctl enable --now docker這個腳本會幫你把Docker Engine和Compose v2插件一起裝好。裝完后驗證一下版本docker --version docker compose version能看到版本號就說明環(huán)境OK了。裝完Docker后建議立刻把當(dāng)前用戶加入docker組這樣后續(xù)操作不用每條命令都加sudosudo usermod -aG docker $USER newgrp docker注意加入docker組后需要重新登錄終端才會生效。這也是我一開始踩過的地方加完組沒重新登錄一直報權(quán)限錯誤白折騰了十分鐘。2.3 為什么我堅持用PostgreSQL而不是SQLiteOpenStock官方Compose配置里默認(rèn)就是把PostgreSQL作為主存儲里面有環(huán)境變量在控制數(shù)據(jù)庫連接。這里我不建議把數(shù)據(jù)庫換成SQLite來“精簡部署”——雖然對單機(jī)用途來說SQLite好像夠用但OpenStock的一些統(tǒng)計查詢涉及多表關(guān)聯(lián)SQLite在高并發(fā)和復(fù)雜查詢下的表現(xiàn)遠(yuǎn)不如PostgreSQL。既然官方已經(jīng)幫你把PostgreSQL編排好了就直接用它。數(shù)據(jù)庫連接的關(guān)鍵環(huán)境變量包括數(shù)據(jù)庫名稱、用戶名、密碼、主機(jī)名和端口。Compose文件里數(shù)據(jù)庫服務(wù)一般會聲明為db應(yīng)用服務(wù)里填的DB_HOSTdb指的就是Compose網(wǎng)絡(luò)里的服務(wù)名而不是你本機(jī)的localhost。這個細(xì)節(jié)如果不理解后面遇到連接失敗時會一臉懵。3. 手把手實操OpenStock完整部署過程環(huán)境準(zhǔn)備好之后就可以開始正式搭建了。整個過程分四步下載項目、修改配置、啟動容器、初始化賬號。跟著走一遍基本是零坑的。3.1 下載項目并確認(rèn)目錄結(jié)構(gòu)項目默認(rèn)部署目錄我用/opt/openstock你也可以用~/openstock差別不大。先把代碼拉下來sudo mkdir -p /opt/openstock sudo chown $USER:$USER /opt/openstock git clone https://github.com/你的倉庫地址/openstock.git /opt/openstock提示如果你在服務(wù)器上訪問GitHub比較慢建議先在本地下載好壓縮包再用scp上傳。這里不展開討論網(wǎng)絡(luò)代理相關(guān)內(nèi)容只提醒這個操作路徑可行。拉下來之后看一下目錄里的關(guān)鍵文件cd /opt/openstock ls -la正常情況下會看到一個docker-compose.yml文件一個.env.example環(huán)境變量示例文件以及backend、frontend等源碼目錄。如果源碼目錄后面沒有特殊定制需求我們根本不用碰全程只操作Compose和環(huán)境變量兩個文件。3.2 編輯docker-compose.yml并理解每一項打開docker-compose.yml內(nèi)容大致長這樣version: 3.8 services: db: image: postgres:15-alpine container_name: openstock_db restart: unless-stopped environment: POSTGRES_DB: openstock POSTGRES_USER: openstock POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - db_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U openstock] interval: 10s timeout: 5s retries: 5 backend: build: ./backend container_name: openstock_backend restart: unless-stopped depends_on: db: condition: service_healthy environment: DB_HOST: db DB_PORT: 5432 DB_NAME: openstock DB_USER: openstock DB_PASSWORD: ${DB_PASSWORD} SECRET_KEY: ${SECRET_KEY} volumes: - uploads:/app/uploads ports: - 127.0.0.1:8000:8000 frontend: build: ./frontend container_name: openstock_frontend restart: unless-stopped depends_on: - backend ports: - 127.0.0.1:8080:80重點看這幾個地方第一數(shù)據(jù)庫的POSTGRES_PASSWORD用了變量引用${DB_PASSWORD}這比把密碼硬寫在Compose文件里要安全得多。就算這個Compose文件被傳到公開倉庫密碼也不會泄露。第二healthcheck配置很關(guān)鍵。backend容器通過depends_on的condition: service_healthy來確保數(shù)據(jù)庫服務(wù)真正就緒后才啟動。如果沒有這個健康檢查backend可能會在數(shù)據(jù)庫還沒初始化完時就嘗試連接連接失敗直接退出。第三上傳目錄/app/uploads掛到了uploads卷。商品圖片如果傳上去重啟容器不會丟不掛卷的話容器一重建圖片全沒了。第四端口這里我做了個保守處理把backend和frontend都只綁定到127.0.0.1不直接暴露公網(wǎng)。前面再用Nginx做反向代理只開放80/443給用戶。這樣能少一層暴露面后文我會細(xì)講。3.3 配置環(huán)境變量文件.env.example文件里列了所有需要你自定義的項復(fù)制一份成.env然后逐個改cp .env.example .env vim .env最少要改三個地方DB_PASSWORD改成你自己的強(qiáng)密碼 SECRET_KEY改成隨機(jī)生成的密鑰生成一個隨機(jī)密鑰的方法openssl rand -hex 32把輸出粘貼到SECRET_KEY后面。你不用理解它內(nèi)部怎么加密會話只要明白這個密鑰相當(dāng)于系統(tǒng)的“主鑰匙”一定要足夠隨機(jī)、一定要保密。如果SECRET_KEY泄露用戶會話就有被偽造的風(fēng)險丟掉的話已簽發(fā)的會話會全部失效用戶需要重新登錄。3.4 啟動并驗證服務(wù)狀態(tài)都配好后執(zhí)行啟動命令docker compose up -d第一次執(zhí)行會拉取鏡像并構(gòu)建前后端耗時比較長。我自己的服務(wù)器跑了大概三到五分鐘取決于網(wǎng)絡(luò)狀況。構(gòu)建完成后用下面命令檢查狀態(tài)docker compose ps期望看到三個服務(wù)都是Up狀態(tài)openstock_db顯示healthy。如果一切正常在服務(wù)器本地測試一下curl http://127.0.0.1:8080返回了HTML內(nèi)容說明前端服務(wù)正常。再用curl http://127.0.0.1:8000/api/health這樣的接口地址探一下后端如果返回JSON結(jié)構(gòu)說明前后端已經(jīng)打通。實操心得啟動后不建議馬上關(guān)終端。先執(zhí)行docker compose logs -f backend實時盯一下后端日志。正常啟動時日志里會有數(shù)據(jù)庫連接成功、服務(wù)監(jiān)聽端口這類記錄。如果看到異常堆棧直接CtrlC停下來然后根據(jù)第5節(jié)的問題排查表去定位比等一會兒再查日志要高效。3.5 配置反向代理用域名訪問如果你是通過IP加端口的方式訪問http://服務(wù)器IP:8080這種形式也能用但不安全也不好看。我是用Nginx做反向代理的還把HTTP自動跳轉(zhuǎn)到了HTTPS。Nginx的配置核心就兩段server塊一段監(jiān)聽80端口的跳轉(zhuǎn)一段監(jiān)聽443端口的業(yè)務(wù)代理server { listen 80; server_name stock.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }HTTPS部分需要先申請好證書把證書路徑填進(jìn)ssl_certificate和ssl_certificate_key即可。證書的申請部署過程屬于另一個話題這里不展開但方向就是這樣。有一個重要提醒很多反代場景下如果不設(shè)置X-Forwarded-Proto頭后端程序會以為當(dāng)前請求還是HTTP導(dǎo)致前端回調(diào)或者登錄態(tài)校驗出問題。我在配置時一開始漏了這行結(jié)果前端登錄成功后一直跳回登錄頁排查了很久才發(fā)現(xiàn)是協(xié)議頭的問題。3.6 初始化后端數(shù)據(jù)與管理員賬號系統(tǒng)起來之后第一次打開前端頁面會進(jìn)入一個引導(dǎo)界面或者默認(rèn)登錄頁。部分版本提供了初始化管理員賬號的入口如果不能通過網(wǎng)頁初始化就進(jìn)入backend容器執(zhí)行。我用的這套流程是在容器內(nèi)完成數(shù)據(jù)庫遷移并創(chuàng)建管理員的docker compose exec backend python manage.py migrate docker compose exec backend python manage.py createsuperusermigrate的作用是把數(shù)據(jù)表結(jié)構(gòu)同步到數(shù)據(jù)庫里。第一次執(zhí)行時PostgreSQL里還是空庫執(zhí)行完這個命令才會生成全部業(yè)務(wù)表。createsuperuser會交互式提示輸入用戶名、郵箱和密碼。這里我建議用戶名不要用簡單的admin密碼也要用強(qiáng)密碼因為這是整個系統(tǒng)的最高權(quán)限入口。如果你打算長期對外使用最好再開兩步驗證別讓管理員賬號裸奔。4. 日常運(yùn)維與數(shù)據(jù)安全規(guī)劃能跑到這一步系統(tǒng)就已經(jīng)能用了。但“能用”和“敢長期用”之間還差一個運(yùn)維規(guī)劃的距離。日常維護(hù)的重點我放在自動化備份、容器升級、數(shù)據(jù)安全三個方向。4.1 數(shù)據(jù)庫備份與恢復(fù)庫存單據(jù)是業(yè)務(wù)數(shù)據(jù)丟了就是災(zāi)難。PostgreSQL的數(shù)據(jù)存在db_data這個命名卷里單靠Docker守護(hù)進(jìn)程管理一旦磁盤故障這個卷就可能隨著整個數(shù)據(jù)盤一起沒了。所以我堅持用cron定時做數(shù)據(jù)庫邏輯備份備份文件放到另一個磁盤目錄有條件的話再同步到對象存儲或移動硬盤。備份腳本我放在/opt/openstock/scripts/backup_db.sh#!/bin/bash BACKUP_DIR/var/backups/openstock DATE$(date %Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR docker compose exec -T db pg_dump -U openstock openstock $BACKUP_DIR/openstock_$DATE.sql find $BACKUP_DIR -name *.sql -mtime 30 -delete腳本里-T參數(shù)很重要它禁用偽終端分配不然在cron環(huán)境中執(zhí)行會報“the input device is not a TTY”的錯誤。這個坑我踩過寫在這里提醒你。然后添加定時任務(wù)crontab -e 0 2 * * * bash /opt/openstock/scripts/backup_db.sh每天凌晨兩點自動備份保留30天?；謴?fù)操作也簡單把備份的SQL文件導(dǎo)進(jìn)數(shù)據(jù)庫即可docker compose exec -T db psql -U openstock openstock openstock_備份日期.sql4.2 鏡像升級與數(shù)據(jù)遷移OpenStock如果發(fā)布了新版本想升級的話先備份再拉取新代碼重新構(gòu)建最后遷移數(shù)據(jù)庫cd /opt/openstock git pull docker compose up -d --build docker compose exec backend python manage.py migrate這里有個細(xì)節(jié)docker compose up -d --build會重新構(gòu)建有變化的鏡像但不會主動刪除舊的鏡像文件。跑幾輪之后docker images里會堆很多none鏡像。用一條命令清理一下docker image prune -f這條命令會刪除所有未被容器引用的懸空鏡像釋放磁盤空間。我習(xí)慣每次升級后都執(zhí)行一下避免磁盤被歷史鏡像占滿。4.3 日志查看與輪轉(zhuǎn)容器日志默認(rèn)由Docker接管長期跑的話也可能占不少磁盤。查看后端實時日志用docker compose logs -f backendDocker的json-file日志驅(qū)動有默認(rèn)大小限制但不同版本默認(rèn)配置不同。保險起見我建議在docker-compose.yml里給服務(wù)加上日志配置限制單文件大小和保留數(shù)量logging: driver: json-file options: max-size: 10m max-file: 3這樣單個容器最多保留3個10MB的日志文件不會出現(xiàn)“日志把磁盤撐爆”的情況。我開始沒加這個限制有次后端接口被腳本頻繁調(diào)用一天就寫了好幾GB日志磁盤直接飄紅后來才老實加上的。5. 搭建和運(yùn)行中的坑我替你趟過了不管文檔寫得多清楚實操中總會遇到幾個“怎么跟教程不一樣”的地方。我把搭建過程中以及后來維護(hù)期間遇到的高頻問題整理成了一張速查表每一行都是實測過的不是抄官方FAQ?，F(xiàn)象可能原因解決思路backend容器啟動后立即退出數(shù)據(jù)庫尚未就緒或賬號密碼不對查看日志確認(rèn)報錯類型確認(rèn).env中DB_PASSWORD與Compose里引用一致確認(rèn)depends_on配置了service_healthy前端能打開但登錄失敗后端API端口不可達(dá)或Nginx反代配置漏了協(xié)議頭先curl http://127.0.0.1:8000測后端連通檢查Nginx是否補(bǔ)了X-Forwarded-Proto上傳圖片后刷新圖片丟失上傳目錄未掛載卷檢查Compose文件中backend服務(wù)是否把/app/uploads掛到命名卷重建容器前務(wù)必確認(rèn)掛載存在數(shù)據(jù)庫連接超時數(shù)據(jù)庫容器拉取鏡像較慢或初始化未完成查看docker compose ps中db是否healthy用docker compose logs db查看數(shù)據(jù)庫初始化日志服務(wù)器重啟后服務(wù)沒有自動恢復(fù)restart策略未設(shè)置在Compose的每個服務(wù)中加上restart: unless-stopped重新up -d生效頁面樣式錯亂前端構(gòu)建時靜態(tài)文件未覆蓋升級時養(yǎng)成先重新構(gòu)建前端再啟動的習(xí)慣必要時docker compose build --no-cache frontend強(qiáng)制重新構(gòu)建舊的備份恢復(fù)后登錄提示會話過期SECRET_KEY發(fā)生了變化恢復(fù)備份后保持SECRET_KEY穩(wěn)定如果換過密鑰讓用戶重新登錄即可除了這張表我還想多分享兩個從實際運(yùn)維里得出的建議。第一個是不要直接用8080端口開公網(wǎng)訪問。這個端口一旦暴露各種掃描工具就會盯上你的服務(wù)。我自己的服務(wù)器有過幾次被掃描撞庫的記錄后來全部改成只監(jiān)聽127.0.0.1再通過Nginx反代出去整個風(fēng)險面就小了很多。第二個是登錄后臺后先建一個只讀賬號給同事用。團(tuán)隊成員如果只是查庫存沒必要給他們管理員權(quán)限。OpenStock的權(quán)限模型支持部分操作放權(quán)最安全的做法永遠(yuǎn)是給每個人最小必要權(quán)限這樣以后出了問題也好定位到底是誰操作的。這個小習(xí)慣能省下很多不必要的扯皮。6. 寫在使用OpenStock半年之后用OpenStock半年多我的整體體會是它把我從“Excel里找?guī)齑妗钡哪嗵独锢顺鰜碜屛抑匦吕斫饬藥齑婀芾淼暮诵膬r值——不是記錄數(shù)字而是讓數(shù)字背后的業(yè)務(wù)動作可追蹤、可復(fù)盤。系統(tǒng)本身不復(fù)雜但因為有完整的單據(jù)流每次月底盤點對賬時我都能快速定位到差異來自哪些單子省掉了以前反復(fù)翻聊天記錄和紙面單證的力氣。最后再分享一個我自己習(xí)慣的小做法每周日晚看一眼低庫存報表把下周要補(bǔ)的貨提前列出來。OpenStock的庫存預(yù)警閾值設(shè)好之后這個報表基本就是自動生成的我只需要在手機(jī)上打開頁面瞄一眼十分鐘就能把補(bǔ)貨計劃定好。這種“系統(tǒng)管細(xì)節(jié)、人做決策”的狀態(tài)才是自建庫存系統(tǒng)真正該有的樣子。如果你也在為庫存亂賬頭疼找一個周末照著這篇文章的步驟把這套系統(tǒng)搭起來試試。通了之后你會回來感謝自己的。