麒麟系统部署检查清单：上线前30分钟，逐项自查这4类问题

接上篇《国产银河麒麟系统开发实录：跑通Streamlit，我踩过的6个坑》------踩过的坑要变成经验，经验要变成清单。本文把上篇的6个坑和更多实战教训，整理成一份可以直接照做的部署前检查清单，外加一个一键自检脚本。物理隔离环境里，部署一次不容易，上线前多花30分钟自查，好过出问题后再跑一趟。

为什么要有一份清单？

信创环境部署有个特点：开发机与生产机物理隔离，代码拷贝过去后，验证机会极少，改一次的成本极高。在这种环境下，"试错"是奢侈品，"一次做对"才是常态。

而我见过太多部署失败，都栽在同一个原因上------不是技术难，是漏项。漏了检查字体、漏了对齐依赖版本、漏了备份旧文件。所以，清单比技术重要。

下面按部署顺序分4部分，逐项自查。

第一部分：环境自检（上机后先做）

1. Python 版本 麒麟系统上 python 命令指向的是 Python 2！必须用 python3：

bash 复制代码

python3 --version   # 期望输出 3.6 ~ 3.8
python --version    # 如果输出 2.7.x，记住永远别用它

2. 中文字体 没有中文字体，matplotlib 和 PIL 画出来的中文全是方块：

bash 复制代码

ls /usr/share/fonts/truetype/wqy/wqy-microhei.ttc 2>/dev/null && echo "✅ 字体存在" || echo "❌ 缺少字体，执行: sudo apt-get install fonts-wqy-microhei"

3. 关键依赖版本 用 pip freeze 对比开发机和生产机的依赖，重点核对三个：

bash 复制代码

python3 -c "import streamlit; print('Streamlit:', streamlit.__version__)"
python3 -c "import pandas; print('pandas:', pandas.__version__)"
python3 -c "import numpy; print('numpy:', numpy.__version__)"

参考兼容组合（经实战验证）：

Python	Streamlit	pandas	状态
3.7.x	1.24.0	1.3.5	✅ 兼容
3.8.x	1.26.0	1.5.3	✅ 兼容
3.9.x	1.28.0	2.0.0	⚠️ 可能有坑
3.12.x	1.50.0	2.0.0	❌ 不建议用于麒麟

建议做法 ：维护两个 requirements 文件------requirements_dev.txt（开发用，版本随意）和 requirements_kylin.txt（生产用，锁死保守版本）。

第二部分：代码自检（拷贝前在开发机做完）

4. Streamlit API 兼容性 width 参数是 Streamlit 1.28.0 才加的，旧版本不认识：

bash 复制代码

grep -rn "st\.button.*width" --include="*.py" . && echo "❌ 发现不兼容用法，删掉 width 参数" || echo "✅ 无 st.button width"
grep -rn "use_container_width" --include="*.py" . && echo "⚠️ use_container_width 已弃用，改为 width='stretch'" || echo "✅ 无弃用用法"

5. pandas 日期比较 .date() 直接比较在 Python 3.8 下会崩（上篇坑1）：

bash 复制代码

grep -rn "\.date()" --include="*.py" . | grep -v "\.to_pydatetime" | head -20

逐个检查，确认都包了 pd.Timestamp() 转换。

6. 字体路径写死 搜索代码里有没有写死的 macOS/Windows 字体路径（上篇坑2、坑3）：

bash 复制代码

grep -rn "PingFang\|SimHei\|msyh\|simhei" --include="*.py" .

有的话改成动态检测：优先麒麟的 /usr/share/fonts/truetype/wqy/wqy-microhei.ttc，再回退其他系统路径。

7. moviepy API 兼容 with_audio（1.x）和 set_audio（2.x）不能写死，用 hasattr 双兼容（上篇坑5）。

8. 上传大小限制 Streamlit 默认上传上限 200MB，业务文件大就提前配好：

toml 复制代码

# .streamlit/config.toml
[server]
maxUploadSize = 500

记得这个文件要一起拷过去！

第三部分：部署前自检（动生产机之前）

9. 备份！备份！备份！

bash 复制代码

cp -r /path/to/app /path/to/app_backup_$(date +%Y%m%d_%H%M%S)

物理隔离环境没有 Git 远程仓库，本地备份就是唯一的后悔药。上篇的6个坑我都踩过，但最险的一次是改坏了整个目录------幸好有备份。

10. 虚拟环境不要拷

同步代码时排除虚拟环境目录，几百MB的包文件只会污染目标目录、拖慢传输：

bash 复制代码

tar --exclude=".venv" --exclude="venv" --exclude="__pycache__" --exclude="*.pyc" \
    -cf - . | (cd /path/to/prod && tar xf -)

11. 端口占用检查

bash 复制代码

ss -tlnp | grep 8501 && echo "⚠️ 8501被占用，换端口启动" || echo "✅ 端口空闲"
streamlit run app.py --server.port 8501 --server.headless true

12. 数据库表结构

代码改了表结构时，CREATE TABLE IF NOT EXISTS 对已存在的表不生效------这是最隐蔽的坑，改表结构后一定要查：

bash 复制代码

sqlite3 data/app.db "PRAGMA table_info(events);"

对照代码里期望的字段，缺了就 ALTER TABLE ... ADD COLUMN。

第四部分：部署后验证（启动后必须做）

13. 健康检查

bash 复制代码

curl -s -o /dev/null -w "%{http_code}" http://localhost:8501/_stcore/health
# 期望输出 200

14. 功能冒烟测试（按业务优先级）

登录/鉴权
日期范围查询（验证坑1）
图表渲染（验证坑2，肉眼看中文是否正常）
文件上传/下载（验证上传限制配置）
视频/报表生成（验证坑3-6）
数据库读写

15. 截图留档

每个页面截一张图存档------万一后续出问题，对比截图能快速判断是代码问题还是环境问题。

彩蛋：一键自检脚本

把下面脚本保存为 pre_deploy_check.sh，拷贝到生产机后直接跑，输出✅❌一目了然：

bash 复制代码

#!/bin/bash
# 麒麟系统部署前自检脚本
echo "========== 麒麟部署自检 =========="

# 1. Python 版本
echo "[1/8] Python 版本"
python3 --version
if python3 -c "import sys; exit(0 if sys.version_info >= (3,6) else 1)"; then
    echo "✅ Python3 可用"
else
    echo "❌ Python 版本过低"
fi

# 2. 中文字体
echo "[2/8] 中文字体"
if [ -f "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc" ]; then
    echo "✅ 文泉驿微米黑存在"
else
    echo "❌ 缺少字体: sudo apt-get install fonts-wqy-microhei"
fi

# 3. 依赖版本
echo "[3/8] 依赖版本"
python3 -c "import streamlit; print('   Streamlit:', streamlit.__version__)"
python3 -c "import pandas; print('   pandas:', pandas.__version__)"

# 4. Streamlit API 兼容性
echo "[4/8] Streamlit API 兼容性"
grep -rn "st\.button.*width" --include="*.py" . > /dev/null 2>&1 && echo "❌ 发现 st.button width 用法" || echo "✅ 无 width 参数"

# 5. pandas 日期比较
echo "[5/8] 日期比较用法"
grep -rn "\.date()" --include="*.py" . > /dev/null 2>&1 && echo "⚠️ 发现 .date() 调用，请确认已用 pd.Timestamp 转换" || echo "✅ 无裸 .date()"

# 6. 上传配置
echo "[6/8] 上传大小配置"
if [ -f ".streamlit/config.toml" ] && grep -q "maxUploadSize" ".streamlit/config.toml"; then
    echo "✅ 上传限制已配置"
else
    echo "⚠️ 未配置 maxUploadSize，默认200MB"
fi

# 7. 端口占用
echo "[7/8] 端口占用"
if ss -tlnp 2>/dev/null | grep -q ":8501 "; then
    echo "⚠️ 8501被占用"
else
    echo "✅ 8501空闲"
fi

# 8. 数据库表结构
echo "[8/8] 数据库"
if [ -f "data/app.db" ]; then
    python3 -c "
import sqlite3
conn = sqlite3.connect('data/app.db')
tables = [r[0] for r in conn.execute(\"SELECT name FROM sqlite_master WHERE type='table'\").fetchall()]
print('   表:', ', '.join(tables) if tables else '无')
conn.close()
"
else
    echo "⚠️ 未找到 data/app.db（首次部署可忽略）"
fi

echo "========== 自检完成 =========="

跑完脚本，✅多的可以部署，❌多的先解决，别硬上。

总结：部署口诀

环境先查版本号，代码先搜旧API； 备份永远第一位，验证不能省一步。

上篇《6个坑》讲的是"踩坑"，本篇讲的是"防坑"。两篇配合使用：踩了坑回来翻清单，没踩坑先跑清单。

下一篇预告：《物理隔离环境下的代码同步方案》------开发机和生产机之间，代码、数据库、资源文件怎么安全高效地同步，这是信创环境绕不开的最后一公里。

系列文章，欢迎收藏转发。如果这份清单帮到了你，评论区告诉我你踩过最痛的坑是哪一个。