277 lines
9.5 KiB
Markdown
277 lines
9.5 KiB
Markdown
# Windows 操作 NAS Docker · 命令手册
|
||
|
||
针对本项目的实际环境整理（身份证识别 API 部署在飞牛 fnOS）。
|
||
|
||
## 本机参数
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| NAS IP | `10.1.1.163` |
|
||
| 项目目录 | `/vol1/1000/Docker/idcard-api` |
|
||
| compose 项目名 | `icd`（镜像名 `icd-idcard-api`） |
|
||
| 容器名 | `idcard-api` |
|
||
| 服务端口 | `8000`（容器内 8000 映射到宿主机 8000） |
|
||
| 宿主机用户 | `owen`（**不在 docker 组，docker 命令都要 `sudo`**） |
|
||
|
||
---
|
||
|
||
## 一、三个操作平面（最容易搞错的地方）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ ① Windows PowerShell（你的电脑） │
|
||
│ 能做：curl.exe 测接口、WinSCP 传文件 │
|
||
│ 不能：任何 docker 命令 │
|
||
│ 提示符：PS C:\Users\Administrator> │
|
||
├─────────────────────────────────────────────┤
|
||
│ ② NAS 宿主机（SSH 连进去） │
|
||
│ 能做：docker / docker compose / sudo / 文件操作 │
|
||
│ 登录：ssh owen@10.1.1.163 │
|
||
│ 提示符：owen@youjiala:/$ │
|
||
├─────────────────────────────────────────────┤
|
||
│ ③ 容器内部（fnOS Docker 界面「终端」按钮） │
|
||
│ 能做：容器内的 ls / grep / cat / env │
|
||
│ 不能：docker 命令（容器里没装 docker CLI） │
|
||
│ 提示符：root@c5bbd0b03ba1:/# │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**判断口诀**：命令里有 `docker` 或要动 NAS 上的文件 → 平面 ②；只是想试试接口通不通 → 平面 ①；想偷懒看容器里某个文件 → 平面 ③（但别在里面敲 docker）。
|
||
|
||
---
|
||
|
||
## 二、快速判断表
|
||
|
||
| 你要做的事 | 在哪里执行 | 需要登录吗 |
|
||
|---|---|---|
|
||
| 测接口通不通（curl） | Windows PowerShell | ❌ 不需要 |
|
||
| 上传/覆盖代码文件 | Windows（WinSCP / 资源管理器） | ❌ 不需要（SFTP） |
|
||
| `docker ps` / `docker logs` | NAS 宿主机 | ✅ `ssh owen@10.1.1.163` |
|
||
| `docker compose build/up` | NAS 宿主机 | ✅ SSH |
|
||
| 看镜像创建时间 | NAS 宿主机 | ✅ SSH |
|
||
| 改 `.env` | WinSCP 或 SSH 均可 | 视习惯 |
|
||
| 查看容器内 `main.py` | NAS 宿主机 `docker exec` | ✅ SSH |
|
||
| 快速瞄一眼容器内文件 | fnOS Docker 界面「终端」 | ❌ 界面点开即可 |
|
||
| 加 docker 组免 sudo | NAS 宿主机 | ✅ SSH |
|
||
|
||
---
|
||
|
||
## 三、Windows 连接方式
|
||
|
||
### SSH 登录宿主机
|
||
|
||
```powershell
|
||
ssh owen@10.1.1.163
|
||
# 首次会问 yes/no，输 yes，然后输 owen 的密码
|
||
# 退出：exit
|
||
```
|
||
|
||
看到提示符 `owen@youjiala:/$` 就说明进去了。
|
||
|
||
### 传文件（WinSCP / FileZilla）
|
||
|
||
- 协议：`SFTP`
|
||
- 主机：`10.1.1.163`，端口 `22`
|
||
- 用户：`owen`
|
||
- 目标目录：`/vol1/1000/Docker/idcard-api`
|
||
|
||
或者在 fnOS 网页的「我的文件 → Docker → idcard-api」里直接上传。
|
||
|
||
### 一次性免 sudo（推荐做一次）
|
||
|
||
```bash
|
||
sudo usermod -aG docker $USER
|
||
newgrp docker # 当前会话立即生效，不用退出重登
|
||
```
|
||
|
||
之后所有 docker 命令都不用加 `sudo` 了。本文档仍按**带 sudo** 写，两种都能用。
|
||
|
||
---
|
||
|
||
## 四、命令速查
|
||
|
||
### 1. 测试接口（Windows PowerShell）
|
||
|
||
> ⚠️ PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名，**必须写 `curl.exe`**。
|
||
|
||
```powershell
|
||
# 健康检查
|
||
curl.exe -s http://10.1.1.163:8000/api/v1/idcard/health
|
||
|
||
# 根路径（服务信息 + 端点清单）
|
||
curl.exe -s http://10.1.1.163:8000/
|
||
|
||
# 识别（带 token）
|
||
curl.exe -X POST http://10.1.1.163:8000/api/v1/idcard/recognize ^
|
||
-H "Authorization: Bearer 你的token" ^
|
||
-F "file=@C:/path/idcard.jpg"
|
||
|
||
# 识别（旧版 X-API-Key 头）
|
||
curl.exe -X POST http://10.1.1.163:8000/api/v1/idcard/recognize ^
|
||
-H "X-API-Key: 你的key" ^
|
||
-F "file=@C:/path/idcard.jpg"
|
||
|
||
# 反向验证：不带 token 应该 401
|
||
curl.exe -X POST http://10.1.1.163:8000/api/v1/idcard/recognize ^
|
||
-F "file=@C:/path/idcard.jpg"
|
||
```
|
||
|
||
> `^` 是 CMD 的续行符。PowerShell 用反引号 `` ` ``，或者直接写成一行。
|
||
|
||
### 2. 首次部署（SSH）
|
||
|
||
```bash
|
||
# ① 建目录（WinSCP 已传过文件可跳过）
|
||
mkdir -p /vol1/1000/Docker/idcard-api
|
||
cd /vol1/1000/Docker/idcard-api
|
||
|
||
# ② 确认文件都在
|
||
ls -la
|
||
|
||
# ③ 配 .env（必须有 .env，.env.example 不生效）
|
||
cp .env.example .env
|
||
vi .env # 或 WinSCP 直接编辑
|
||
|
||
# ④ 检查 compose 解析结果
|
||
sudo docker compose -p icd config | grep -A2 API_TOKENS
|
||
|
||
# ⑤ 首次构建（会装 numpy/onnxruntime，3-5 分钟）
|
||
sudo docker compose -p icd up -d --build
|
||
|
||
# ⑥ 跟踪日志
|
||
sudo docker logs -f idcard-api
|
||
```
|
||
|
||
### 3. 日常更新代码（SSH）
|
||
|
||
```bash
|
||
cd /vol1/1000/Docker/idcard-api
|
||
sudo docker compose -p icd up -d --build # 增量构建，10-30 秒
|
||
```
|
||
|
||
或者用项目自带脚本（会校验镜像里的代码真的更新了）：
|
||
|
||
```bash
|
||
bash /vol1/1000/Docker/idcard-api/deploy.sh
|
||
```
|
||
|
||
**只改了 `.env` 或 `docker-compose.yml`**（不需要 build）：
|
||
|
||
```bash
|
||
sudo docker compose -p icd up -d
|
||
```
|
||
|
||
**怀疑缓存坏了**（全量重建，3-5 分钟）：
|
||
|
||
```bash
|
||
sudo docker compose -p icd build --no-cache
|
||
sudo docker compose -p icd up -d --force-recreate
|
||
```
|
||
|
||
### 4. 排查"改了代码没生效"
|
||
|
||
这是本项目最容易踩的坑：**fnOS 的「重新部署」只重建容器，不重建镜像**。
|
||
|
||
```bash
|
||
# ① 容器里的代码是新版吗？0=旧代码，≥1=新代码
|
||
sudo docker exec idcard-api grep -c auth_enabled /app/app/main.py
|
||
|
||
# ② 镜像什么时候建的？
|
||
sudo docker images --format "{{.Repository}}:{{.Tag}} {{.ID}} 创建于 {{.CreatedSince}}" | grep -i idcard
|
||
|
||
# ③ compose 项目真实工作目录（和你上传的目录一致吗？）
|
||
sudo docker inspect idcard-api --format '{{index .Config.Labels "com.docker.compose.project.working_dir"}}'
|
||
|
||
# ④ 环境变量注入情况
|
||
sudo docker exec idcard-api env | grep -E "API_TOKENS|API_KEY|CLIENT_SECRET"
|
||
|
||
# ⑤ 容器状态与端口
|
||
sudo docker ps --filter name=idcard-api
|
||
```
|
||
|
||
### 5. 日常运维（SSH）
|
||
|
||
```bash
|
||
# 实时日志
|
||
sudo docker logs -f idcard-api
|
||
|
||
# 最近 50 行
|
||
sudo docker logs --tail 50 idcard-api
|
||
|
||
# 过滤调用记录（看谁在调、耗时多少）
|
||
sudo docker logs --tail 100 idcard-api | grep "recognize by="
|
||
|
||
# 内存占用（关键：1C2G 机器要盯这个）
|
||
sudo docker stats --no-stream idcard-api
|
||
|
||
# 重启（不重新读 .env，改配置请用 up -d）
|
||
sudo docker restart idcard-api
|
||
|
||
# 停掉并删除容器 + 镜像
|
||
sudo docker compose -p icd down --rmi local
|
||
|
||
# 进容器内部 shell（在宿主机执行）
|
||
sudo docker exec -it idcard-api bash
|
||
```
|
||
|
||
### 6. 容器内部（fnOS 界面「终端」里执行）
|
||
|
||
```bash
|
||
grep -c auth_enabled /app/app/main.py # 代码版本
|
||
ls -l --time-style=long-iso /app/app/ # 文件时间
|
||
echo $API_TOKENS # 环境变量
|
||
```
|
||
|
||
> 这里**不能**跑 `docker` 命令。要跑 docker，回宿主机 SSH。
|
||
|
||
---
|
||
|
||
## 五、完整流程：从改代码到生效
|
||
|
||
```bash
|
||
# ① Windows：改本地文件（WorkBuddy 生成）
|
||
|
||
# ② Windows：WinSCP 上传到 /vol1/1000/Docker/idcard-api
|
||
# 注意保持目录结构：app/、Dockerfile、docker-compose.yml 等
|
||
|
||
# ③ SSH 登录 NAS
|
||
ssh owen@10.1.1.163
|
||
|
||
# ④ 构建并启动
|
||
cd /vol1/1000/Docker/idcard-api
|
||
sudo docker compose -p icd up -d --build
|
||
|
||
# ⑤ 校验镜像里的代码真的换了（关键！别跳过）
|
||
sudo docker exec idcard-api grep -c 你的新特征字符串 /app/app/main.py
|
||
|
||
# ⑥ 退出 SSH，回 Windows 测接口
|
||
exit
|
||
```
|
||
|
||
```powershell
|
||
curl.exe -s http://10.1.1.163:8000/api/v1/idcard/health
|
||
```
|
||
|
||
---
|
||
|
||
## 六、错误对照表（本对话踩过的坑）
|
||
|
||
| 报错 | 在哪发生 | 原因 | 解决 |
|
||
|---|---|---|---|
|
||
| `docker: command not found` | 容器内部 | 在容器里跑 docker 命令 | 回宿主机 SSH，或去掉 `docker exec` 前缀用容器内路径 |
|
||
| `permission denied ... docker.sock` | 宿主机 | 用户不在 docker 组 | 命令前加 `sudo`，或 `usermod -aG docker` |
|
||
| `401 Unauthorized ... docker.fnnas.com` | 宿主机 build | fnOS 加速源不授权，且会覆盖 daemon.json | Dockerfile 用 `ARG BASE_IMAGE=国内仓库全路径`，绕开 daemon 配置 |
|
||
| `could not find ... dockerfile` | 宿主机 build | Dockerfile 首行 `# syntax=` 触发前端镜像拉取 | 删掉该行 |
|
||
| health 返回缺字段 / 行为没变化 | Windows 测接口 | 镜像没重建，跑的还是旧镜像 | 必须 `up -d --build`，不能只「重新部署」 |
|
||
| `.env` 改了不生效 | 宿主机 | ①文件叫 `.env.example` ②只 `restart` 了 | 创建真正的 `.env`，然后 `up -d`（不是 restart） |
|
||
| `curl: 无法将...识别为 cmdlet` | Windows | `curl` 是 PowerShell 别名 | 用 `curl.exe` |
|
||
| `\r: command not found` | 宿主机 | Windows CRLF 换行 | `sed -i 's/\r$//' 脚本名.sh` |
|
||
| 识别返回空，前端提示"未识别到信息" | C# 调用方 | 401 被静默吞掉（没检查状态码） | C# 加鉴权头 + 检查 `IsSuccessStatusCode` |
|
||
|
||
---
|
||
|
||
## 七、两条铁律
|
||
|
||
1. **改代码必须 build**。`docker compose up -d`（不带 `--build`）在镜像已存在时不会重新构建，只重建容器。代码改动一点都进不去。
|
||
2. **`-p icd` 不能省**。项目名不是目录名，不带这个参数会创建新项目，容器和镜像都对不上。
|