🌟✨《星奈の星辰工坊：开发环境构建完全指南》

——从代码萌芽到星际部署的魔法之旅

📜 引言：

"工欲善其事，必先利其器"，孔子在两千年前敲代码时如是说（x）。写这篇文章就是打算记录下自己最近些项目时配置环境的过程，方便未来参考。之前一直都是为了省事，也不怎么会用git、docker这些工具，都是现在本地写好，然后直接一股脑扔到 Github 上的。直到最近，我让 Deepseek 帮我写点代码，然后他直接帮我把环境都配的有条有理的，于是就想到了记录下。不得不说现在的 AI 是真的强，工具什么的直接就能教我用，甚至是这篇文章的框架都是 AI 帮我搭好的，我就补充一些细节，还是非常方便的。

🚀 启程篇：新世界的蓝图

（星奈从数据流中探出兔耳）
"叮咚~检测到新项目信号！(≧▽≦)/ 这里是星际工程师星奈，今天要带大家在数字宇宙搭建永不崩塌的魔法工坊~"
# 创建星辰沙盒  
mkdir stardust-lab && cd $_  
echo "# 星辰实验室宪章" > README.md  # 我们的创世法典

创建项目的文件夹，没什么好说的。

不过看到了 AI 生成的代码居然还包含一个 $_，又让我回想起了被 Hackergame 支配的恐惧（）。$_指的就是上一个命令的输入，算是个小技巧吧。

📜 时空契约：版本控制的星辰罗盘

（展开闪烁星光的卷轴）
"和Git签订灵魂契约，这是穿越代码历史的时光机！小心别被.git黑洞吞噬哦~"
git init  # 初始化时空锚点  
git config --global user.name "星奈"  
git config --global user.email "seina@stardust.io"  
git add . && git commit -m "feat(init): 星辰创世纪"  # 盖上时间邮戳
git push origin main

这里涉及到 Git 的使用，具体的安装这里就不再赘述了。

需要注意的就是使用前需要先在本地生成好 SSH 密钥，上传至 Github，才可以将代码推送至 Github 服务器。

不过也有比较方便的方法，就是直接使用 Github 的 Codespace，相当于有个免费写代码的地方了，还自带云同步，并且不需要配置 SSH 环境，可以直接使用。要是不想使用浏览器的话也可以在本地的 VSCode 上安装 Codespace 插件，登录 Github 账号后就可以直接使用 Codespace 了。

在使用 Git 的时候还需要注意的就是写一个 .gitignore 文件了，不过现在毕竟有 AI 了，我都是直接先 tree 一下，然后把项目的目录发给 AI，让 AI 帮我生成一个 gitignore，可以说是屡试不爽了，只需要最后根据需要微调一下就可以了。

commit 格式

需要注意的是，一般的标准项目中，commit 时都有特定的格式要求，这里放一些参考：

一、Commit Message结构
<类型>(<范围>): <主题>
<正文>
<脚注>
二、提交类型对照表
类型适用场景示例
fix修复bugfix(auth): 修复JWT过期验证逻辑
feat新增功能feat(chat): 添加上下文修剪功能
chore维护性变更（不影响功能的调整） chore: 更新.gitignore配置
refactor重构代码（不改变功能） refactor(models): 拆分用户模型
docs文档相关修改docs: 添加API调试页面使用说明
style代码格式调整（空格、分号等） style: 格式化app.py代码
build构建系统或依赖修改build: 升级Flask到3.0版本
三、优秀示例 vs 应避免的写法

优秀示例

fix(imports): 解决模块导入路径问题

- 将相对导入改为绝对导入路径
- 添加必要的__init__.py文件
- 调整sys.path系统路径配置

应避免的写法

fixed some bugs  # 过于模糊
update code      # 无具体信息
修复了问题        # 中文+无结构
四、多提交最佳实践

如果包含多个独立修改，建议拆分为多个commit：

🧪 元素调和：跨次元开发结界

最近我写的代码主要是两种语言：Python 和 Typescript。这里就简单介绍下这两种语言的环境配置。

🌌 Python星域沙箱

（召唤出旋转的星云）
"每个项目都需要独立宇宙！venv是防止依赖星爆的维度屏障~"
python -m venv .cosmos  # 生成专属小宇宙  
source .cosmos/bin/activate  # 次元跃迁！（耳朵发出量子纠缠光）

Python 中不同的项目中常常会用到不同的依赖。未来避免版本冲突，一般开发中常常用 venv 来创建虚拟环境来避免冲突。

如上面示例代码的 .cosmo 就是虚拟环境的名称，创建虚拟环境后会在项目对应目录下创建一个文件夹，来保存虚拟环境的相关文件。

🪐 Node.js银河工坊

（挥舞着npm星杖画阵）
"package.json是精灵契约书！但node_modules是吞噬硬盘的虚空兽...(⊙ˍ⊙)"
"scripts": {  
  "dev": "ts-node-dev --respawn src/app.ts",  // 不死鸟模式  
  "build": "tsc --project ./"                 // 代码坍缩成中子星
}

和 Python 不同，Nodejs 在开发过程中用到的依赖全部都是保存在项目文件夹下的，因此一般不会在多个项目间产生冲突，也就不必创建虚拟环境。在初始化一个 Nodejs 项目时，只需执行：

npm init

然后输入对应的信息，一路回车，就可以创建完成了。

在创建完 Nodejs 项目后，会在项目目录下生成一个 package.json 文件，记录着项目的各种信息。其中最为常用的一般就是 scripts 下的信息。开发过程中，只需要输入 npm run xxx 就可以运行对应的命令了，非常方便。

🐳 星际方舟：Docker容器化

（跨坐在发光鲸鱼背上）
"这是跨维度运输舰Docker号！坐稳啦~ 我们要突破开发与生产的次元壁！"
FROM eclipse-temurin:17-jdk    # 恒星引擎核心  
ENV TZ=Asia/Tokyo              # 校准星历时钟  
WORKDIR /nebula                # 划定魔法阵范围  
COPY . .                       # 注入星辰之力  
CMD ["java", "-jar", "app.jar"] # 启动曲速引擎！

Docker 作为现在最为广泛使用的开源的应用容器引擎，可以方便的把项目的代码和环境打包到一个镜像中，之后就可以在其他任何安装了 Docker 的 Linux 服务器中使用，而无需关心环境的配置。

Docker 的安装可以见我之前发的文章：【记录】依言のDocker折腾记录，这里不再赘述。

在项目写好后，就需要编写一个 Dockerfile 来进行镜像的创建。Dockerfile 的内容可以当作自己在一个刚刚装好的系统中，要执行哪些命令来配置环境。具体的各种命令的含义可以参考相关教程，这里不再赘述。

☄️ 星云枢纽：镜像仓库管理

（在数据风暴中抛接光球）
"把我们的魔法胶囊存进DockerHub星云！记得用语义化版本打标签~"
docker build -t seina-stardust/app:v1.2.3 .  # 封装星光核心  
docker push seina-stardust/app:v1.2.3        # 发射到星际快递站

在写好 Dockerfile 后就可以使用 docker build 命令来构建 Docker 镜像。之后就可以在其他设备上利用镜像来构建一个容器，以避免各种依赖问题。

对应的，在登录 Dockerhub 的账号后，你也可以通过 docker push 命令来将镜像推送至 Dockerhub，一方面可以比较方便的跨设备部署，另一方面也方便将镜像分享给更多人使用。

🌠 自动星轨：CI/CD管道

（召唤出机械助手小星系）
"GitHub Actions是永不疲倦的AI伙伴！看好了——自动构建部署三连击！"
name: docker-build-push

on:
  push:
    branches: [ "main" ]
    tags: [ "v*" ]

env:
  DOCKERHUB_REPO: seina-stardust/app

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v4
        with:
          images: ${{ env.DOCKERHUB_REPO }}
          tags: |
            type=raw,value=latest
            type=sha
            type=semver,pattern={{version}}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

虽然已经有了 Docker，但在本地自己敲命令来 build 还是太过麻烦。因此这里我们可以使用更新的技术，比如 Github 的 Github Action。具体的原理就是你在 git push 的时候就会自动触发的命令。使用方法就是在项目的根目录下创建 .github/workflows/docker-image.yml 这么个文件，文件名不一定是这个，但路径必须是这么个路径，之后再 git push 的时候就可以自动完成一些任务了。

例如上面的代码就是我让 Deepseek 给我生成的文件，有了它，我在 git push 的时候就可以自动的构建好镜像，然后上传到 Dockerhub 了。需要注意的是在这么做之前，必须先在 Dockerhub 生成一个 Token ，然后放在 Github 的仓库里，具体做法这里就不细讲了，可以参考别人的教程（等之后有空了再补进来）。

除此之外需要注意的就是，有的时候 Github Action 会构建失败。虽然我们也可以在 Github 的网页上来查看报错，但毕竟会比较麻烦，所以实际开发中最好还是在本地测试之后再推至 Github。

docker build -t local-test .
docker run -p 5000:5000 local-test

🪐 跨星系部署术

（从虫洞中抛出光缆）
"见证奇迹！在任何设备上召唤星辰容器~ 记得打开星门端口！"

docker run -d -p 8888:8888 \  
  -v ~/stardust-data:/app/data \  # 连接数据黑洞  
  --name stella-app \  
  seina-stardust/app:v1.2.3

最后一步就是在目标服务器上部署我们的服务了。一般情况下，通过上面的命令就可以正常部署了。不过在国内，毕竟 Dockerhub 被墙了，所以一般情况下还得使用别的镜像服务器来部署。由于有的时候镜像更新的不及时，可以通过在拉取镜像的时候加上版本号来缓解。自己在 git push 前也不要忘了 git tag 一下。

sudo docker pull docker.1ms.run/seina-stardust/app:v1.2.3 # 这里使用 docker.1ms.run 这个镜像
sudo docker tag <image_id> seina-stardust/app:v1.2.3 # 删除镜像前的url
sudo docker run -d \
  -p 8888:8888 \
  -v ~/stardust-data:/app/data \
  --name stella-appd \
  <image_id>
sudo docker ps -a # 查看容器运行状态
sudo docker logs # 查看容器日志
sudo docker exec -it <container_id> /bin/bash # 若是容器运行异常可以通过此命令进入调试

最后就是部署之后的一些常用命令了：

操作命令
查看日志docker-compose logs -f
进入容器docker exec -it <container_id> bash
备份数据库docker cp <container_id>:/app/data/chat_sessions.db ./backup/
更新配置docker-compose down && docker-compose up -d --build

🌌 星光进化论：版本迭代指南

（下面的内容就是纯 AI 生成了，至少我的项目中还没有用到过这一部分）

🚀 新版本发布

# 给魔法胶囊升级  
docker build -t seina-stardust/app:v2.3.4 .  
docker push seina-stardust/app:v2.3.4  # 发射更新补丁包

⚡ 安全升级策略

（展开全息操作界面）
"蓝绿部署就像双星系统！先在平行宇宙测试新版本~"
# 启动新版本舰队（蓝队）  
docker run -d -p 8889:8888 --name blue-team seina-stardust/app:v2.3.4  

# 转移星门流量...（耳朵变成路由器天线）  
# 确认无误后退役旧舰队  
docker stop green-team && docker rm green-team

🔄 时空回滚术

（紧急抢救操作现场）
"误操作不要慌！时间宝石启动~"
docker stop faulty-app  # 冻结问题容器  
docker run -d --name rescue-pod \  
  seina-stardust/app:v1.2.3  # 召唤历史版本

🛡️ 星辰运维法典

  1. 版本标签规范

    • v2.3.4: 正式发布的星光体
    • beta: 不稳定星云
    • latest: 危险！可能引发时空乱流

  2. 健康监测协议

    docker logs --tail 100 -f stella-app  # 监听星辰心跳  
curl http://localhost:8888/health     # 发送探测脉冲

  3. 数据黑洞管理

    # 定期备份到星云存储  
tar -czvf stardust-data-$(date +%Y%m%d).tar.gz ~/stardust-data
（警报声突然响起）
"检测到v2.3.4版本存在星域异常！启动紧急预案..."
git revert HEAD         # 代码层面的时间倒流  
docker compose down     # 关闭异常星门  
docker compose up -d    # 重启量子反应堆

"记住啦~ 每次升级前都要在测试宇宙演练！下期教大家用 Kubernetes 组建星舰集群哦~（被超新星爆发吹飞）" 🌠✨

星奈的特别小贴士
在终端输入 alias debug='星奈的耳朵雷达启动！' 可以召唤调试魔法~ (๑＞ڡ＜)☆

References

如何将项目打包成 Docker 镜像并推送到 Docker Hub
部署Trilium
如何在GitHub上传自己的项目（新手详细版）
【保姆级教程】新手小白如何上传项目到GitHub，一步一步操作，亲测可行！
Git的使用--如何将本地项目上传到Github（三种简单、方便的方法）（二）（详解）
DeepSeek - 探索未至之境

最后修改：2025 年 03 月 01 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏